Консоль

Конфигурация

Документация по настройке файла gt.config.json

Обзор

Файл gt.config.json используется для конфигурации GT в вашем проекте. Его следует размещать в корне проекта.

Мастер настройки CLI npx gtx-cli init создаст файл gt.config.json в вашем проекте.

Конфигурация

Файл gt.config.json принимает следующие свойства (но не ограничивается ими):

  • defaultLocale: Локаль по умолчанию для вашего проекта. Это локаль, на которой написан исходный контент. Также это резервная локаль для вашего проекта (если используется gt-next или gt-react).

  • locales: Массив локалей вашего проекта. Это локали, на которые вы хотите перевести проект. См. поддерживаемые локали для получения дополнительной информации. Если вы используете gt-next или gt-react, это также локали, поддерживаемые вашим приложением.

  • files: Объект, содержащий сведения о контенте, который вы хотите переводить.

  • stageTranslations: Необязательный логический флаг, указывающий, настроен ли проект на использование ручной проверки.

  • src: Необязательный массив шаблонов путей (glob) для исходных файлов. По умолчанию:

[
  "src/**/*.{js,jsx,ts,tsx}",
  "app/**/*.{js,jsx,ts,tsx}",
  "pages/**/*.{js,jsx,ts,tsx}",
  "components/**/*.{js,jsx,ts,tsx}"
]
  • dictionary: Необязательная строка, задающая относительный путь к файлу словаря.

Чтобы упростить проверку файла gt.config.json, вы можете использовать JSON Schema для CLI.

Добавьте её в начало файла gt.config.json:

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
}

Ниже приведён шаблон файла gt.config.json:

gt.config.json
{
  "$schema": "https://assets.gtx.dev/config-schema.json",
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "..."
    },
    "json": {
      "include": [...]
    },
    "mdx": {
      "include": [...]
    },
    "md": {
      "include": [...]
    }
  },
  "src": [
    "src/**/*.{ts,tsx}",
  ],
  "dictionary": "./dictionary.json"
}

Псевдонимы локалей

Если вы хотите назначить локали псевдоним (например, cn вместо zh), укажите пользовательское сопоставление в файле gt.config.json.

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
    }
  }
}

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

gt.config.json
{
  "customMapping": {
    "cn": {
      "code": "zh",
      "name": "Китайский",
    }
  }
}

files

Поддерживаемые типы файлов

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

  • gt: файлы General Translation.
  • json: файлы JSON.
  • yaml: файлы YAML.
  • mdx: файлы компонентов Markdown (MDX).
  • md: файлы Markdown (MD).
  • js: файлы JavaScript.
  • ts: файлы TypeScript.

Каждый тип файла должен соответствовать объекту, содержащему один или несколько из следующих ключей:

  • include
  • exclude
  • transform
  • output

include

Если используется, значение ключа include должно быть массивом glob‑шаблонов, которые соответствуют файлам, подлежащим переводу.

В своих glob‑шаблонах необходимо использовать плейсхолдер [locale], чтобы исходные файлы корректно находились, а переведённые — сохранялись в нужном месте. CLI‑инструмент при поиске переводимых файлов заменит плейсхолдер [locale] значением defaultLocale.

CLI‑инструмент сохранит переведённые файлы по соответствующему пути, заменив плейсхолдер [locale] кодом целевой локали.

{
  "include": ["docs/[locale]/**/*.json"]
}

exclude

Если используется, значение ключа exclude должно быть массивом glob‑шаблонов, которые соответствуют файлам, подлежащим исключению из перевода.

Шаблон аналогичен шаблону include, за исключением того, что плейсхолдер [locale] необязателен. Если он указан, он будет заменён значением defaultLocale.

{
  "exclude": ["docs/[locale]/exclude/**/*.json"]
}

Если нужно исключить файлы из перевода для всех локалей, используйте плейсхолдер [locales] вместо [locale].

{
  "exclude": ["docs/[locales]/exclude/**/*.json"]
}

transform

transform может быть строкой или объектом.

Если transform — строка, он задаёт переименование файла. В ней должен быть подстановочный символ *, который будет заменён исходным именем файла (всё, что идёт до первой .).

Например, если вы хотите, чтобы у всех переведённых файлов расширение было .[locale].json вместо .json, можно использовать следующую конфигурацию:

{
  "transform": "*.[locale].json"
}

В качестве альтернативы, если transform — объект, он должен содержать следующие свойства:

  • match (необязательно): шаблон регулярного выражения для поиска строк; поддерживаются группы захвата
  • replace (обязательно): строка или шаблон регулярного выражения для замены найденного совпадения

Оба значения поддерживают группы захвата и применяются к полному относительному имени выходного файла.

{
  "transform": {
    "match": "^(.*)$",
    "replace": "{locale}/$1"
  }
}

Например, указанная выше конфигурация приведёт к сохранению переведённых файлов в подкаталоге целевой локали.

Специальные плейсхолдеры

Параметр transform поддерживает несколько специальных плейсхолдеров, которые можно использовать как в строках match, так и в строках replace:

  • {locale}: плейсхолдер кода локали, который ведет себя по‑разному в зависимости от контекста:
    • В строках match: заменяется на код локали по умолчанию (например, "en") для облегчения поиска исходных файлов
    • В строках replace: заменяется на код целевой локали (например, "fr", "es") для формируемых переведенных файлов

Например, если ваша локаль по умолчанию — "en", а вы переводите на "fr":

  • Шаблон match вида "content/{locale}/file.md" превращается в "content/en/file.md"
  • Шаблон replace вида "content/{locale}/file.md" превращается в "content/fr/file.md"

Кроме того, любое другое свойство из getLocaleProperties можно использовать как плейсхолдер с таким же контекстно‑зависимым поведением.

Это полезно, если вашей документации или i18n‑фреймворку требуется определённое расширение файла для переведённых файлов вместо маршрутизации локали через подкаталоги.

output

Этот ключ используется исключительно для файлов General Translation, в частности для локального сохранения переводов. Если вы используете GT CDN, этот ключ не требуется.

Значением должна быть строка с плейсхолдером [locale], указывающим путь, по которому будут сохранены переводы.

Например, если вы хотите сохранить испанские переводы в файл ui.es.json в каталоге public/i18n, используйте следующую строку:

{
  "output": "public/i18n/[locale].json"
}

Этот вариант следует использовать только в том случае, если вы применяете gt-next или gt-react и хотите сохранять переводы локально вместо использования GT CDN.

В настоящее время для каждой локали может быть создан только один файл.

Тип файла: gt

Поддерживаемые ключи

  • output (обязательный)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
  }
}

Эта конфигурация позволит утилите CLI сохранять французские и испанские переводы в каталог public/i18n/[locale].json.

По умолчанию при такой конфигурации утилита CLI не будет публиковать переводы в GT CDN.

Тип файла: json

Поддерживаемые ключи

  • include (обязательный)
  • exclude (необязательный)
  • transform (необязательный)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "json": {
      "include": ["json_files/[locale]/**/*.json"],
      "exclude": ["json_files/[locale]/exclude/**/*.json"]
    }
  }
}

Предположим, что локаль по умолчанию в вашем проекте — en, и вы хотите перевести проект на fr и es.

С этой конфигурацией CLI будет искать все файлы JSON в подкаталоге json_files/en/ и сохранять переведённые файлы в json_files/fr/ и json_files/es/.

Он будет игнорировать любые файлы в подкаталоге json_files/en/exclude/.

Тип файла: yaml

Поддерживаемые ключи

  • include (обязательный)
  • exclude (необязательный)
  • transform (необязательный)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "yaml": {
      "include": ["yaml_files/[locale]/**/*.yaml"],
      "exclude": ["yaml_files/[locale]/exclude/**/*.yaml"]
    }
  }
}

Допустим, локаль по умолчанию в вашем проекте — en, и вы хотите перевести проект на fr и es.

С такой конфигурацией CLI будет искать все YAML‑файлы в подкаталоге yaml_files/en/ и сохранять переведённые файлы в yaml_files/fr/ и yaml_files/es/.

При этом будут игнорироваться любые файлы в подкаталоге yaml_files/en/exclude/.

Тип файла: mdx

Поддерживаемые ключи

  • include (обязательно)
  • exclude (необязательно)
  • transform (необязательно)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    }
  }
}

Эта конфигурация укажет инструменту CLI искать все файлы MDX в каталоге content/docs/en и сохранять переведённые файлы в каталоге content/docs/ja.

Ключ transform изменяет расширение переведённых файлов на .ja.mdx.

Тип файла: md

Поддерживаемые ключи

  • include (обязательно)
  • exclude (опционально)
  • transform (опционально)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["ja"],
  "files": {
    "md": {
      "include": ["content/docs/[locale]/**/*.md"],
      "exclude": ["content/docs/[locale]/exclude/**/*.md"],
      "transform": "*.[locale].md"
    }
  }
}

Эта конфигурация укажет утилите CLI искать все файлы MD в каталоге content/docs/en и сохранять переведённые файлы в каталог content/docs/ja.

Ключ transform меняет расширение переведённых файлов на .ja.md.

Все файлы в каталоге content/docs/en/exclude будут игнорироваться.

Тип файла: js

Поддерживаемые ключи

  • include (обязательный)
  • exclude (необязательный)
  • transform (необязательный)

Пример

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "js": {
      "include": ["scripts/[locale]/**/*.js"]
    }
  }
}

Эта конфигурация укажет утилите CLI искать все файлы JavaScript в каталоге scripts/en и сохранять переведённые файлы в каталоги scripts/fr и scripts/es.

Ключ transform изменяет расширение переведённых файлов на .fr.js и .es.js соответственно (из .js).

Тип файла: ts

Поддерживаемые ключи

  • include (обязательный)
  • exclude (необязательный)
  • transform (необязательный)

Пример

gt.config.json
{ 
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "ts": {
      "include": ["scripts/[locale]/**/*.ts"]
    }
  }
}

Эта конфигурация укажет CLI‑инструменту искать все файлы TypeScript в каталоге scripts/en и сохранять переведённые файлы в каталоги scripts/fr и scripts/es.

Ключ transform меняет расширение переведённых файлов на .fr.ts и .es.ts соответственно (из .ts).

Пример конфигурации

Разберём пример файла gt.config.json:

gt.config.json
{
  "defaultLocale": "en",
  "locales": ["fr", "es"],
  "files": {
    "gt": {
      "output": "public/i18n/[locale].json"
    },
    "mdx": {
      "include": ["content/docs/[locale]/**/*.mdx"],
      "transform": "*.[locale].mdx"
    },
    "json": {
      "include": ["resources/[locale]/**/*.json"],
      "exclude": ["resources/[locale]/exclude/**/*.json"]
    }
  }
}

В этом примере мы переводим следующие файлы одним вызовом gtx-cli translate:

  • Все MDX‑файлы в каталоге content/docs/en.
  • Все JSON‑файлы в каталоге resources/en (за исключением файлов в resources/en/exclude).
  • Все встроенные компоненты <T> в вашем проекте на React или Next.js.
  • Файл dictionary.[json|js|ts].

GT: Переводы будут сохранены в public/i18n/es.json и public/i18n/fr.json. Эти файлы можно загрузить с помощью loadTranslations.

MDX: Переводы будут сохранены в каталогах content/docs/fr и content/docs/es. Расширения файлов будут изменены на .fr.mdx и .es.mdx (из .mdx).

JSON: Переводы будут сохранены в каталогах resources/fr и resources/es.

Следующие шаги

Узнайте, как использовать команду init для создания этого файла конфигурации.

Насколько полезно это руководство?

На этой странице

Обзор
Конфигурация
Псевдонимы локалей
files
Поддерживаемые типы файлов
include
exclude
transform
Специальные плейсхолдеры
output
Тип файла: gt
Тип файла: json
Тип файла: yaml
Тип файла: mdx
Тип файла: md
Тип файла: js
Тип файла: ts
Пример конфигурации
Следующие шаги
Конфигурация