i18n

Плагины NocoBase поддерживают многоязычную i18n как для клиентской, так и для серверной части. Благодаря унифицированному механизму вы можете легко реализовать многоязычный контент в плагинах.

Управление многоязычными файлами

Многоязычные файлы плагина хранятся в каталоге src/locale. Рекомендуется именовать их по коду языка, например:

|- /plugin-hello
  |- /src
    |- /locale
      |- en-US.json   # Английский язык
      |- zh-CN.json   # Китайский язык

Каждый языковой файл экспортирует объект JSON, содержащий все записи перевода для этого языка, например:

// zh-CN.json
{
  "Hello": "你好",
  "World": "世界",
  "Enter your name": "请输入你的名字",
  "Your name is {{name}}": "你的名字是 {{name}}"
}
// en-US.json
{
  "Hello": "Hello",
  "World": "World",
  "Enter your name": "Enter your name",
  "Your name is {{name}}": "Your name is {{name}}"
}

При первом добавлении языковых файлов необходимо перезапустить приложение, чтобы они вступили в силу. Проверить записи перевода можно через API: http://localhost:13000/api/app:getLang?locale=zh-CN

Глобальный экземпляр i18n

app.i18n — это глобальный экземпляр i18n, подходящий для глобальных сценариев CLI и общих сценариев плагина. Его можно комбинировать с inquirer для реализации взаимодействия в командной строке:

import select from '@inquirer/select';
import input from '@inquirer/input';

export class PluginSampleI18nServer extends Plugin {
  load() {
    this.app.command('test-i18n').action(async () => {
      const answer1 = await select({
        message: 'Select a language',
        choices: [
          { name: '中文', value: 'zh-CN' },
          { name: 'English', value: 'en-US' }
        ]
      });

      await this.app.changeLanguage(answer1);

      const answer2 = await input({
        message: app.i18n.t('Enter your name')
      });

      console.log(app.i18n.t('Your name is {{name}}', { name: answer2 }));
    });
  }
}

app.i18n.t(text, options) используется для перевода текста и поддерживает переменные шаблона.

Контекст запроса i18n

ctx.i18n в каждом запросе является клоном глобального экземпляра i18n и независимо возвращает локализованный контент в зависимости от языка клиента.

Установка языка клиента

  • Строка запроса:
GET /?locale=en-US HTTP/1.1
Host: localhost:13000
  • Заголовок запроса (рекомендуется):
GET / HTTP/1.1
Host: localhost:13000
X-Locale: en-US

Использование в middleware

export class PluginSampleI18nServer extends Plugin {
  load() {
    this.app.use(async (ctx, next) => {
      if (ctx.path === '/api/test-i18n') {
        ctx.body = ctx.t('Hello', { ns: '@my-project/plugin-hello' });
      }
      await next();
    });
  }
}

Доступ к http://localhost:13000/api/test-i18n?locale=zh-CN вернет 你好 (по-китайски «Привет»).

Встроенный i18n плагина

Плагины могут напрямую использовать plugin.t(key, options) для получения переводов:

export class PluginSampleI18nServer extends Plugin {
  load() {
    this.app.use(async (ctx, next) => {
      if (ctx.path === '/api/plugin-i18n') {
        ctx.body = this.plugin.t('Hello');
      }
      await next();
    });
  }
}

plugin.t(text) эквивалентен ctx.t(text, { ns }).

Связанные API

  • app.i18n
  • app.t(text, options)
  • ctx.i18n
  • ctx.t(text, options)
  • plugin.t()
  • tExpr(text, options)