snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

server/public/pluginapi/i18n/doc.go

@@ -0,0 +1,2 @@
+// package i18n provides methods to read translations files and localize strings.
+package i18n

server/public/pluginapi/i18n/i18n.go

@@ -0,0 +1,136 @@
+package i18n
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/nicksnyder/go-i18n/v2/i18n"
+	"github.com/pkg/errors"
+	"golang.org/x/text/language"
+
+	"github.com/mattermost/mattermost/server/public/model"
+)
+
+// PluginAPI is the plugin API interface required to manage translations.
+type PluginAPI interface {
+	GetBundlePath() (string, error)
+	GetConfig() *model.Config
+	GetUser(userID string) (*model.User, *model.AppError)
+	LogWarn(msg string, keyValuePairs ...any)
+}
+
+// Message is a string that can be localized.
+//
+// See https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/i18n?tab=doc#Message for more details.
+type Message = i18n.Message
+
+// LocalizeConfig configures a call to the Localize method on Localizer.
+//
+// See https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/i18n?tab=doc#LocalizeConfig for more details.
+type LocalizeConfig = i18n.LocalizeConfig
+
+// Localizer provides Localize and MustLocalize methods that return localized messages.
+//
+// See https://pkg.go.dev/github.com/nicksnyder/go-i18n/v2/i18n?tab=doc#Localizer for more details.
+type Localizer = i18n.Localizer
+
+// Bundle stores a set of messages and pluralization rules.
+// Most plugins only need a single bundle
+// that is initialized on activation.
+// It is not goroutine safe to modify the bundle while Localizers
+// are reading from it.
+type Bundle struct {
+	*i18n.Bundle
+	api PluginAPI
+}
+
+// InitBundle loads all localization files  from a given path into a bundle and return this.
+// path is a relative path in the plugin bundle, e.g. assets/i18n.
+// Every file except the ones named active.*.json.
+// The default language is English.
+func InitBundle(api PluginAPI, path string) (*Bundle, error) {
+	bundle := &Bundle{
+		Bundle: i18n.NewBundle(language.English),
+		api:    api,
+	}
+	bundle.RegisterUnmarshalFunc("json", json.Unmarshal)
+
+	bundlePath, err := api.GetBundlePath()
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to get bundle path")
+	}
+
+	i18nDir := filepath.Join(bundlePath, path)
+
+	files, err := os.ReadDir(i18nDir)
+	if err != nil {
+		return nil, errors.Wrap(err, "failed to open i18n directory")
+	}
+
+	for _, file := range files {
+		if !strings.HasPrefix(file.Name(), "active.") {
+			continue
+		}
+
+		if !strings.HasSuffix(file.Name(), ".json") {
+			continue
+		}
+
+		if file.Name() == "active.en.json" {
+			continue
+		}
+
+		_, err = bundle.LoadMessageFile(filepath.Join(i18nDir, file.Name()))
+		if err != nil {
+			return nil, errors.Wrapf(err, "failed to load message file %s", file.Name())
+		}
+	}
+
+	return bundle, nil
+}
+
+// GetUserLocalizer returns a localizer that localizes in the users locale.
+func (b *Bundle) GetUserLocalizer(userID string) *i18n.Localizer {
+	user, err := b.api.GetUser(userID)
+	if err != nil {
+		b.api.LogWarn("Failed get user's locale", "error", err.Error())
+		return b.GetServerLocalizer()
+	}
+
+	return i18n.NewLocalizer(b.Bundle, user.Locale)
+}
+
+// GetServerLocalizer returns a localizer that localizes in the default server locale.
+//
+// This is useful for situations where a messages is shown to every user,
+// independent of the users locale.
+func (b *Bundle) GetServerLocalizer() *i18n.Localizer {
+	local := *b.api.GetConfig().LocalizationSettings.DefaultServerLocale
+
+	return i18n.NewLocalizer(b.Bundle, local)
+}
+
+// LocalizeDefaultMessage localizer the provided message.
+// An empty string is returned when the localization fails.
+func (b *Bundle) LocalizeDefaultMessage(l *Localizer, m *Message) string {
+	s, err := l.LocalizeMessage(m)
+	if err != nil {
+		b.api.LogWarn("Failed to localize message", "message ID", m.ID, "error", err.Error())
+		return ""
+	}
+
+	return s
+}
+
+// LocalizeWithConfig localizer the provided localize config.
+// An empty string is returned when the localization fails.
+func (b *Bundle) LocalizeWithConfig(l *Localizer, lc *LocalizeConfig) string {
+	s, err := l.Localize(lc)
+	if err != nil {
+		b.api.LogWarn("Failed to localize with config", "error", err.Error())
+		return ""
+	}
+	return s
+}

server/public/pluginapi/i18n/i18n_test.go

@@ -0,0 +1,296 @@
+package i18n_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/text/language"
+
+	"github.com/mattermost/mattermost/server/public/model"
+	"github.com/mattermost/mattermost/server/public/plugin"
+	"github.com/mattermost/mattermost/server/public/plugin/plugintest"
+	"github.com/mattermost/mattermost/server/public/pluginapi/i18n"
+)
+
+//nolint:govet
+func ExampleInitBundle() {
+	type Plugin struct {
+		plugin.MattermostPlugin
+
+		b *i18n.Bundle
+	}
+
+	p := Plugin{}
+	b, err := i18n.InitBundle(p.API, filepath.Join("assets", "i18n"))
+	if err != nil {
+		panic(err)
+	}
+
+	p.b = b
+}
+
+func TestInitBundle(t *testing.T) {
+	t.Run("fine", func(t *testing.T) {
+		dir, err := os.MkdirTemp("", "")
+		require.NoError(t, err)
+
+		defer os.RemoveAll(dir)
+
+		// Create assets/i18n dir
+		i18nDir := filepath.Join(dir, "assets", "i18n")
+		err = os.MkdirAll(i18nDir, 0o700)
+		require.NoError(t, err)
+
+		file := filepath.Join(i18nDir, "active.de.json")
+		content := []byte("{}")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		// Add en translation file.
+		// InitBundle should ignore it.
+		file = filepath.Join(i18nDir, "active.en.json")
+		content = []byte("")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		// Add json junk file
+		file = filepath.Join(i18nDir, "foo.json")
+		content = []byte("")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		// Add active. junk file
+		file = filepath.Join(i18nDir, "active.foo")
+		content = []byte("")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		api := &plugintest.API{}
+		api.On("GetBundlePath").Return(dir, nil)
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, "assets/i18n")
+		assert.NoError(t, err)
+		assert.NotNil(t, b)
+
+		assert.ElementsMatch(t, []language.Tag{language.English, language.German}, b.LanguageTags())
+	})
+
+	t.Run("fine", func(t *testing.T) {
+		dir, err := os.MkdirTemp("", "")
+		require.NoError(t, err)
+
+		defer os.RemoveAll(dir)
+
+		// Create assets/i18n dir
+		i18nDir := filepath.Join(dir, "assets", "i18n")
+		err = os.MkdirAll(i18nDir, 0o700)
+		require.NoError(t, err)
+
+		file := filepath.Join(i18nDir, "active.de.json")
+		content := []byte("{}")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		// Add translation file with invalid content
+		file = filepath.Join(i18nDir, "active.es.json")
+		content = []byte("foo bar")
+		err = os.WriteFile(file, content, 0o600)
+		require.NoError(t, err)
+
+		api := &plugintest.API{}
+		api.On("GetBundlePath").Return(dir, nil)
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, "assets/i18n")
+		assert.Error(t, err)
+		assert.Nil(t, b)
+	})
+}
+
+func TestLocalizeDefaultMessage(t *testing.T) {
+	t.Run("fine", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "en"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetServerLocalizer()
+		m := &i18n.Message{
+			Other: "test message",
+		}
+
+		assert.Equal(t, m.Other, b.LocalizeDefaultMessage(l, m))
+	})
+
+	t.Run("empty message", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "en"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		api.On("LogWarn", mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string")).Return()
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetServerLocalizer()
+		m := &i18n.Message{}
+
+		assert.Equal(t, "", b.LocalizeDefaultMessage(l, m))
+	})
+}
+
+func TestLocalizeWithConfig(t *testing.T) {
+	t.Run("fine", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "en"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetServerLocalizer()
+		lc := &i18n.LocalizeConfig{
+			DefaultMessage: &i18n.Message{
+				Other: "test messsage",
+			},
+		}
+
+		assert.Equal(t, lc.DefaultMessage.Other, b.LocalizeWithConfig(l, lc))
+	})
+
+	t.Run("empty config", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "en"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		api.On("LogWarn", mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string")).Return()
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetServerLocalizer()
+		lc := &i18n.LocalizeConfig{}
+
+		assert.Equal(t, "", b.LocalizeWithConfig(l, lc))
+	})
+
+	t.Run("empty message", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "en"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		api.On("LogWarn", mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string")).Return()
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetServerLocalizer()
+		lc := &i18n.LocalizeConfig{
+			DefaultMessage: &i18n.Message{},
+		}
+
+		assert.Equal(t, "", b.LocalizeWithConfig(l, lc))
+	})
+}
+func TestGetUserLocalizer(t *testing.T) {
+	t.Run("fine", func(t *testing.T) {
+		api := &plugintest.API{}
+		api.On("GetUser", "userID").Return(&model.User{
+			Locale: "de",
+		}, nil)
+		api.On("GetBundlePath").Return(".", nil)
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetUserLocalizer("userID")
+		assert.NotNil(t, l)
+
+		enMessage := &i18n.Message{
+			Other: "a",
+		}
+
+		deMessage := &i18n.Message{
+			Other: "b",
+		}
+
+		err = b.Bundle.AddMessages(language.German, deMessage)
+		require.NoError(t, err)
+
+		assert.Equal(t, deMessage.Other, b.LocalizeDefaultMessage(l, enMessage))
+	})
+
+	t.Run("error", func(t *testing.T) {
+		api := &plugintest.API{}
+		defaultServerLocale := "es"
+		api.On("GetConfig").Return(&model.Config{
+			LocalizationSettings: model.LocalizationSettings{
+				DefaultServerLocale: &defaultServerLocale,
+			},
+		})
+		api.On("GetBundlePath").Return(".", nil)
+		api.On("GetUser", "userID").Return(nil, &model.AppError{})
+		api.On("LogWarn", mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string"),
+			mock.AnythingOfType("string"), mock.AnythingOfType("string")).Return()
+		defer api.AssertExpectations(t)
+
+		b, err := i18n.InitBundle(api, ".")
+		require.NoError(t, err)
+
+		l := b.GetUserLocalizer("userID")
+		assert.NotNil(t, l)
+
+		enMessage := &i18n.Message{
+			Other: "a",
+		}
+
+		esMessage := &i18n.Message{
+			Other: "b",
+		}
+
+		err = b.Bundle.AddMessages(language.Spanish, esMessage)
+		require.NoError(t, err)
+
+		assert.Equal(t, esMessage.Other, b.LocalizeDefaultMessage(l, enMessage))
+	})
+}