Переводы

Обзор

Приложения Twenty создаются на английском: строки в вашем исходном коде и манифесте являются исходным текстом на английском, en — это исходная локаль, с которой вы переводите, а любая непереведенная локаль будет использовать ее по умолчанию. В вашем приложении есть два типа переводимого текста, и оба проходят через один и тот же каталог locales/:

Метки манифеста — имена объектов и полей, заголовки представлений, пункты меню и другие строки, объявленные в метаданных вашего приложения.
Строки фронтенд-компонентов — текст интерфейса, который отображают ваши фронтенд-компоненты React.

Вы помечаете переводимые строки, извлекаете их в каталоги для каждой локали, переводите эти каталоги, и сборка отдает правильный язык для текущего пользователя — без дополнительной настройки.

Пометка строк front-component

Импортируйте вспомогательные функции перевода из twenty-sdk/front-component:

import { Trans, t, msg, useTranslate } from 'twenty-sdk/front-component';

const STATUSES = [
  { id: 'draft', label: msg('Draft') },
  { id: 'sent', label: msg('Sent') },
];

const Card = ({ count, name }: { count: number; name: string }) => {
  const { t } = useTranslate();

  return (
    <section>
      {/* Static text — reactive to the user's locale */}
      <Trans>Loading postcard…</Trans>

      {/* Disambiguate identical sources with a context */}
      <Trans context="card-title">Untitled</Trans>

      {/* Interpolation: pass values explicitly */}
      <p>{t('Hi {name}', { name })}</p>
      <p>{t('Saved {count} cards', { count })}</p>

      {/* Resolve a lazily-declared descriptor */}
      <ul>
        {STATUSES.map((s) => (
          <li key={s.id}>{t(s.label)}</li>
        ))}
      </ul>
    </section>
  );
};

Когда что использовать

Trans — статический текст в JSX. Используйте пропсы message и values для интерполяции, как в Trans message="Hi {name}" values={{ name }}; интерполяция напрямую в дочерних элементах не может быть статически извлечена.
useTranslate().t — динамические строки внутри компонента. Повторно рендерится, когда пользователь переключает язык. Предпочтительно использовать это внутри render.
t(...) (импортируемая напрямую) — немедленный перевод, который можно использовать где угодно, включая обработчики событий, вспомогательные функции и область видимости модуля, — не только внутри render.
msg(...) — ленивый дескриптор для строк, объявленных как данные (константы, конфигурация). Разрешите его позже с помощью t(descriptor).

Контекст

Передайте context, чтобы различать одинаковые исходные строки, которые переводятся по-разному:

t({ message: 'Open', context: 'door' });
t({ message: 'Open', context: 'window' });
<Trans context="card-title">Untitled</Trans>;

Контекстные строки отображаются в каталогах локалей в виде группы, индексируемой по их контексту: "\<context>": { "\<message>": "\<translation>" }. Манифестные метки являются контекстными по своей природе — каждая из них несёт метаданные о своей роли (objectMetadata.labelSingular, fieldMetadata.label, view.name, …), поэтому одно и то же слово может переводиться по‑разному как имя объекта и как имя представления.

Извлечение и перевод

Выполните команду извлечения из каталога вашего приложения:

twenty app translations extract                  # collect strings into locales/en.json
twenty app translations extract --locale fr-FR   # also scaffold a target locale

При извлечении собираются как метки манифеста, так и строки t()/msg()/Trans из исходного кода вашего фронт‑компонента в locales/\<locale>.json, где ключом является исходная строка. Заполните переводы:

// locales/fr-FR.json
{
  "Loading postcard…": "Chargement de la carte…",
  "Hi {name}": "Bonjour {name}",
  "Saved {count} cards": "{count} cartes enregistrées",
  "door": {
    "Open": "Ouvrir"
  },
  "objectMetadata.labelSingular": {
    "Postcard": "Carte postale"
  }
}

Строки без контекста являются плоскими записями; контекстные строки — включая каждую метку манифеста — вложены под своим ключом контекста. Заполнители, такие как {name}, подставляются во время выполнения — сохраните их в переводе. Для любой пустой строки используется исходный текст.

Как это работает

twenty app build компилирует каталоги и предоставляет нужный язык для текущего пользователя: метки манифеста разрешаются на стороне сервера, а каталоги фронтенд-компонентов встраиваются в каждый бандл компонента. Во время выполнения компонент считывает локаль из своего контекста выполнения (текущий язык хоста) и разрешает каждую строку по своему каталогу, используя исходный текст, если перевод отсутствует. Переключение языка в хосте повторно рендерит строки Trans и useTranslate().t в реальном времени. Метки манифеста компилируются при каждой синхронизации — одинаково при twenty app build, twenty app apply и непрерывном отслеживании twenty app dev, — поэтому достаточно отредактировать файл локали и выполнить синхронизацию, чтобы увидеть новый текст. Каталоги фронтенд-компонентов встраиваются в каждый бандл компонента во время сборки, поэтому изменение одного из них по-прежнему требует повторного запуска twenty app build (и повторного развертывания).

Получение переводов

twenty app pull записывает опубликованные переводы приложения обратно в locales/. Опубликованный каталог индексируется по идентификатору сообщения, поэтому pull восстанавливает читаемую форму только для строк, исходный текст которых он может видеть: меток полученных им метаданных и строк t()/msg()/Trans фронтенд-компонентов, присутствующих в проекте. Всё остальное сохраняется как есть в locales/compiled/\<locale>.json с ключом в виде идентификатора сообщения. Сборка объединяет эти файлы в каталог (запись в locales/\<locale>.json имеет приоритет над скомпилированной записью с тем же идентификатором), twenty app translations extract оставляет их без изменений, а каждое получение перезаписывает их, поэтому они сокращаются по мере добавления в dерево исходного кода приложения. Не редактируйте их вручную; выполняйте перевод в locales/\<locale>.json. Проект без папки locales/ ничего не сообщает о переводах, поэтому синхронизация из него не изменяет уже опубликованные приложением данные. Чтобы намеренно удалить опубликованные переводы, сохраните папку и удалите файлы локалей внутри неё: папка locales/, которая не компилируется ни в одну локаль, является явным объявлением, и синхронизация выполняет очистку соответствующим образом. Дочерние текстовые элементы Trans могут занимать несколько строк — пробельные символы схлопываются так же, как их схлопывает JSX, поэтому оба этих варианта извлекаются в ключ Welcome back:

<Trans>Welcome back</Trans>
<Trans>
  Welcome
  back
</Trans>

Разработчики

Приложения

API

Самостоятельный хостинг

Внести вклад

Библиотека интерфейса

Обзор

Пометка строк front-component

Когда что использовать

Контекст

Извлечение и перевод

Как это работает

Получение переводов

​Обзор

​Пометка строк front-component

​Когда что использовать

​Контекст

​Извлечение и перевод

​Как это работает

​Получение переводов

Обзор

Пометка строк front-component

Когда что использовать

Контекст

Извлечение и перевод

Как это работает

Получение переводов