# General Translation Knowledge Base: Как перевести файлы локалей в формате YAML? URL: https://generaltranslation.com/ru/kb/translate-yaml-files.mdx Docs index: https://generaltranslation.com/llms.txt Description: Переводите только строковые значения, а ключи, плейсхолдеры вроде %{name} или {{name}} и якоря оставляйте без изменений. Заключайте в кавычки значения, которые содержат двоеточие или начинаются с % или {, задайте для каждого файла корневой ключ локали или имя файла и добавьте ключи форм множественного числа, которые нужны языку перевода. CLI от General Translation переводит значения YAML на месте и не трогает ключи. Category: Перевод Last updated: 2026-10-28 Authors: General Translation Team Published: 2026-10-28 Файл локали в формате YAML сопоставляет ключи со строками, которые видит пользователь, — по одному файлу (или одному ключу верхнего уровня) на каждый язык. Перевести такой файл — значит заменить строковые значения, оставив ключи, плейсхолдеры и структуру файла ровно в том виде, в каком их ожидает фреймворк. С YAML это сложнее, чем с JSON: двоеточие без кавычек или `%` в начале значения ломают парсинг, а `no` может превратиться в логическое значение. Поэтому даже перевод, который читается правильно, может дать файл, который ваше приложение отклонит или прочитает неверно. ## Типичные схемы размещения локалей в YAML Каждый фреймворк указывает язык в своём месте и использует собственный синтаксис плейсхолдеров, и переведённый файл должен соблюдать те же правила: | Фреймворк | Исходный файл | Где указывается язык | Плейсхолдеры | Формы множественного числа | | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------- | ------------------------------------------ | ---------------------------------------------- | | [Rails I18n](https://guides.rubyonrails.org/i18n.html) | `config/locales/en.yml` | Ключ верхнего уровня (`en:`) | `%{name}` | Ключи `one` и `other`; с rails-i18n — больше | | [Symfony](https://symfony.com/doc/current/translation.html#translation-resource-file-names-and-locations) | `translations/messages.en.yaml` | Имя файла (`domain.locale.yaml`) | `%name%` или `{name}` в файлах `+intl-icu` | Формы множественного числа ICU внутри строки | | [Hugo](https://gohugo.io/functions/lang/translate/#translation-tables) | `i18n/en.yaml` | Имя файла | Шаблоны Go, например `{{ . }}` | Ключи CLDR (`one`, `few`, `many`, `other`) | | i18next с [i18next-fs-backend](https://github.com/i18next/i18next-fs-backend) | `locales/en/common.yml` | Каталог | `{{name}}` | Ключи с суффиксами, например `_one` и `_other` | | vue-i18n с [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) | `locales/en.yaml` | Имя файла | `{name}` | Формы в одной строке через вертикальную черту | Строже всего к структуре относится Rails. Согласно [руководству Rails](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), загружаются все файлы `.yml` и `.rb` из `config/locales`, и в каждом файле «ключ верхнего уровня — это локаль». Испанский файл должен начинаться с `es:` независимо от имени файла. ## Подводные камни YAML, из-за которых ломаются переведённые файлы Вот файл Rails, составленный так, чтобы все значения сохранились после перевода: ```yaml title="config/locales/en.yml" en: checkout: title: "Note: prices include VAT" joined: "%{name} joined your team" confirm_no: "No" terms: | By paying, you agree to our terms. Refunds take 5 to 7 days. items: one: "%{count} item" other: "%{count} items" ``` Каждая строка защищает от типичной ошибки: * **Двоеточия.** `title: Note: prices include VAT` без кавычек — синтаксическая ошибка, а в переводе может появиться двоеточие, которого не было в английском тексте. * **Значения, начинающиеся со служебного символа.** Простое значение не может начинаться с `%`, `{`, `[`, `@` или обратной кавычки. `joined: %{name} joined your team` вызывает ошибку разбора, а `{{name}} joined` воспринимается как начало сопоставления. При переводе порядок слов меняется, поэтому плейсхолдер, стоявший в английском в середине предложения, часто оказывается в начале. Именно поэтому в документации Hugo `'{{ . }} day'` заключено в кавычки. * **Логические значения.** Синтаксический анализатор YAML в Ruby следует YAML 1.1, поэтому `yes`, `no`, `on` и `off` без кавычек превращаются в `true` и `false`; анализаторы YAML 1.2, включая большинство инструментов JavaScript, читают их как строки. В руководстве Rails сказано, что [такие ключи нужно экранировать](https://guides.rubyonrails.org/i18n.html#configuring-the-load-paths-and-default-locale), и то же касается значений. Даже норвежский файл с корнем `no:` загружается в Ruby под ключом `false`. * **Блочные скаляры.** `|` сохраняет переносы строк, а `>` заменяет их пробелами. Переведённые строки должны сохранять отступ блока, иначе значение оборвётся раньше времени или файл перестанет разбираться. * **Якоря и алиасы.** `&name` определяет блок, а `*name` повторно его использует, поэтому изменение значения с якорем затрагивает все алиасы. Rails их загружает, но в unplugin-vue-i18n указано, что YAML-ресурсы [не поддерживают алиасы](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n), так что, прежде чем на них полагаться, проверьте свой загрузчик. Если оставить строки `title` и `joined` без кавычек, каждую в отдельном файле, анализатор Ruby (Ruby 2.6, Psych 3.1) отклонит обе ещё до того, как Rails увидит хотя бы один ключ: ```text title="Output" unquoted-colon.yml: mapping values are not allowed in this context at line 3 column 16 unquoted-placeholder.yml: found character that cannot start any token while scanning for the next token at line 3 column 13 ``` Проще всего заключать в кавычки каждое значение: строка в двойных кавычках всегда остаётся строкой, а `%{name}`, двоеточия и `No` — обычным текстом. ### Ключи форм множественного числа различаются в зависимости от языка В английском используются `one` и `other`, но в русском и польском нужны ещё `few` и `many`. Отсутствующие ключи не вызывают ошибки. Если используется бэкенд обработки форм множественного числа из gem-пакета i18n и русское правило множественного числа вроде того, что поставляется с rails-i18n, то в файле, переведённом с английского ключ за ключом, для всех чисел, требующих формы `few`, молча подставляется `other`. Оба русских файла ниже содержат переводы General Translation: ```text title="Output" count key-by-key (one, other) complete (one, few, many, other) 1 У вас 1 непрочитанное сообщение. У вас 1 непрочитанное сообщение. 3 У вас 3 непрочитанных сообщений. У вас 3 непрочитанных сообщения. 5 У вас 5 непрочитанных сообщений. У вас 5 непрочитанных сообщений. 22 У вас 22 непрочитанных сообщений. У вас 22 непрочитанных сообщения. ``` Как отмечается в [руководстве по Rails](https://guides.rubyonrails.org/i18n.html#locale-specific-rules), по умолчанию действуют только английские правила множественного числа, а остальные добавляет бэкенд I18n `Pluralization` или гем rails-i18n. В таблицах переводов Hugo используются те же категории CLDR — от `zero` до `other`. ### Корневой ключ локали нужно изменить В Rails переведённый файл, который по-прежнему начинается с `en:`, не вызывает ошибки. Он просто загружается как английский: в тесте с gem i18n испанский файл с оставленным корневым ключом `en:` заменил английский заголовок испанским, а `I18n.t` для `es` вернул сообщение об отсутствующем переводе. Переименуйте корневой ключ в каждом переведённом файле и не забывайте синхронизировать `config.i18n.available_locales`. ## Способы перевода файлов локалей в формате YAML | Подход | Ключи и заполнители | Ключи форм множественного числа | Контекст для коротких строк | Учёт изменений | | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | Вручную | Безопасно, если переводчик знает YAML | Добавляются, если переводчик знает правила языка | Переводчик может уточнить | Вручную при каждом изменении | | [i18n-tasks](https://github.com/glebm/i18n-tasks) `translate-missing` (Rails) с Google Translate, DeepL или OpenAI | Перед отправкой заменяет `%{...}` токенами | `missing` сообщает об отсутствующих формах множественного числа, если загружены правила rails-i18n | Параметры и промпты для каждого бэкенда | Заполняет недостающие ключи; изменённый английский текст повторно не переводится | | Система управления переводами (TMS) | Разбираются в соответствии с форматом | Зависит от TMS | Скриншоты, комментарии, глоссарий | Синхронизация с репозиторием или обмен файлами | | Скрипт с LLM, обрабатывающий файл | Обычно сохраняются, но правильность кавычек не гарантирована | Добавляются, только если явно попросить | Всё, что вы укажете в промпте | Каждый раз перезапуск и проверка | | [CLI General Translation](/docs/cli/reference/formats/yaml-files) | Переводит только строковые значения; ключи не меняются | Переводит ключи из вашего источника | Glossary, пользовательские промпты, метаданные для отдельных ключей | При каждом запуске повторно использует переводы неизменённых строк | Если речь идёт об одном-двух небольших файлах, правьте их вручную. Выбирайте i18n-tasks, если приложению на Rails нужна проверка недостающих ключей и вас устраивает заполнять пробелы машинным переводом с последующей самостоятельной проверкой. (О том, как эти инструменты дополняют друг друга, см. [General Translation и i18n-tasks](/kb/general-translation-vs-i18n-tasks).) Используйте [TMS](/kb/what-is-a-translation-management-system), если файлами занимаются переводчики. General Translation подойдёт, если все файлы локалей должны генерироваться заново при каждом изменении английского текста, а терминология — оставаться единой для приложения, документации и маркетингового сайта. ## Перевод YAML-файлов с помощью General Translation CLI от General Translation — `gt` — переводит файлы `.yaml` и `.yml`, если в `gt.config.json` указана запись `yaml`. Плейсхолдер `[locale]` обозначает место, куда подставляется язык, поэтому форматы с локалью в имени файла работают без доработок. Для Symfony шаблон `translations/*.[locale].yaml` сопоставляет `messages+intl-icu.en.yaml` с `messages+intl-icu.fr.yaml`; для Hugo: ```json title="gt.config.json" { "defaultLocale": "en", "locales": ["de", "pt-BR"], "files": { "yaml": { "include": ["i18n/[locale].yaml"] } } } ``` Проверено на `gt` 2.26.11: механизм разрешения путей в CLI сопоставляет `i18n/en.yaml` с `i18n/de.yaml` и `i18n/pt-BR.yaml`, что соответствует именам файлов Hugo с языковыми тегами. Войдите с помощью [`npx gt login`](/docs/cli/reference/commands/login) и задайте идентификатор проекта ([учётные данные CLI](/docs/cli/guides/configuring#credentials)), импортируйте существующие переводы командой [`npx gt upload`](/docs/cli/reference/commands/upload), а затем выполните [`npx gt translate`](/docs/cli/reference/commands/translate). General Translation переводит строковые значения и не трогает всё остальное: ключи, числа, булевы значения и комментарии остаются на месте, а блок с якорем переводится один раз, и его алиасы по-прежнему на него ссылаются. Поэтому некоторые особенности фреймворков придётся учесть вам: * **Корневые ключи локалей в Rails.** CLI не переименовывает ключи, в том числе ключ верхнего уровня `en:`, а опция [`transform`](/docs/cli/reference/config#files) переименовывает выходные файлы, а не ключи. Храните для CLI рабочие файлы без корневого ключа, например `translations/en.yml`, и добавляйте корневой ключ локали при экспорте в `config/locales`. (Короткий скрипт экспорта см. в статье [General Translation vs. Rails I18n](/kb/general-translation-vs-rails-i18n).) * **Ключи форм множественного числа.** CLI переводит только те ключи форм множественного числа, которые есть в источнике, поэтому русский файл, полученный из английского источника с `one`/`other`, будет содержать `one` и `other`. Запустите `i18n-tasks missing` с подключённым rails-i18n, чтобы найти ключи `few` и `many`, которые ещё нужно добавить. * **`yes`, `no`, `on` и `off` без кавычек.** General Translation разбирает YAML по правилам версии 1.2, где эти значения считаются строками, поэтому они переводятся как текст. Заключайте их в кавычки в источнике — в Rails это и так рекомендуется. * **Синтаксис библиотек.** Пользовательский синтаксис строк, например сообщения ICU, поддерживается для `i18next` и `next-intl`; при использовании других библиотек проверьте строки с пользовательским синтаксисом после первого запуска. Чтобы уточнить смысл короткой строки, например «Save», добавьте сопутствующий файл `.metadata.yaml` с заметкой `context` или ограничением `maxChars` для каждого ключа ([метаданные, привязанные к ключам](/docs/cli/reference/formats/yaml-files#metadata)). Glossary и пользовательские промпты в [контекстной группе](/docs/platform/dashboard/guides/defining-context-for-translations) обеспечивают единую терминологию продукта во всех ваших YAML-каталогах и во всех остальных проектах группы, а рецензенты могут [редактировать переводы в панели управления](/docs/platform/dashboard/guides/reviewing-translations). Если кто-то отредактировал переведённый файл локально, выполните [`npx gt save-local`](/docs/cli/reference/commands/save-local) перед следующим запуском, чтобы изменения не были перезаписаны. После каждого запуска загрузите файлы так же, как это делает ваше приложение: `i18n-tasks missing` и `i18n-tasks check-consistent-interpolations` для Rails, `lint:translations` для Symfony и сборка для Hugo. (Настройку для Symfony см. в статье [General Translation vs. Symfony Translation](/kb/general-translation-vs-symfony-translation), а если ваши каталоги в формате JSON — в статье [How do I translate i18n JSON files?](/kb/translate-json-files).) ## Частые вопросы ### Нужно ли заключать в кавычки каждое значение в YAML-файле локали? Да, заключать в кавычки каждое значение — самый надёжный подход. Значение в двойных кавычках всегда считается строкой, поэтому двоеточия, `%{name}` в начале значения и слова вроде `No` не повлияют на разбор файла — ни до перевода, ни после. ### Почему приложение Rails выдаёт «translation missing» для языка, на который я уже перевёл текст? Сначала проверьте ключ верхнего уровня в файле. Если корневым ключом файла по-прежнему остаётся `en:`, он загружается как английский, и у новой локали не оказывается ключей. Также убедитесь, что локаль указана в `config.i18n.available_locales`. ### Можно ли использовать якоря и алиасы в файлах локалей? Rails их поддерживает, но некоторые загрузчики — нет, в том числе unplugin-vue-i18n для vue-i18n. Перевод значения с якорем меняет все ссылающиеся на него алиасы, поэтому используйте их только для текста, который везде должен быть одинаковым. ## Главное * Переводите только значения; ключи, заполнители вроде `%{name}` и `{{name}}`, а также отступы блоков оставляйте без изменений. * Заключайте в кавычки значения, содержащие двоеточия или начинающиеся с `%` или `{`, а также слова вроде `yes`, `no`, `on` и `off`: без кавычек Ruby воспримет их как логические значения. * Для русского и польского языков нужны ключи `few` и `many`, которых нет в английском источнике; без них Rails молча откатывается к `other`. * У каждого файла Rails должен быть собственный корневой ключ локали: испанский файл с корнем `en:` загрузится как английский. * CLI General Translation переводит строковые значения YAML с помощью `"yaml": { "include": [...] }` и [`npx gt translate`](/docs/cli/reference/commands/translate), сохраняя ключи, комментарии и якоря; за корневые ключи Rails и недостающие ключи форм множественного числа отвечаете вы. ## Related questions - [General Translation и Rails I18n: нужны ли оба?](https://generaltranslation.com/ru/kb/general-translation-vs-rails-i18n.mdx): Rails I18n находит сообщения и форматирует даты и числа. General Translation создаёт переводы, поддерживает их в актуальном состоянии по мере изменения английского текста и предоставляет вашей команде панель управления для проверки. Используйте оба инструмента, чтобы выпускать переведённые каталоги Rails с каждым релизом. - [General Translation или i18n-tasks: что выбрать?](https://generaltranslation.com/ru/kb/general-translation-vs-i18n-tasks.mdx): i18n-tasks — это Ruby-gem, который находит отсутствующие и неиспользуемые ключи Rails I18N, наводит порядок в файлах локалей и умеет заполнять недостающие ключи с помощью Google Translate, DeepL, OpenAI, Yandex или watsonx. General Translation переводит файлы локалей целиком с учётом вашего Glossary и пользовательских промптов, а результат можно проверить в панели управления. Эти инструменты решают разные задачи, и многим командам пригодятся оба. - [General Translation или Symfony Translation: что выбрать?](https://generaltranslation.com/ru/kb/general-translation-vs-symfony-translation.mdx): Symfony Translation выполняет рендеринг сообщений в PHP и Twig. General Translation переводит его YAML-каталоги в CI, поддерживает их в актуальном состоянии при изменении исходного текста и даёт рецензентам панель управления для их редактирования. Оставьте рендеринг за Symfony и добавьте автоматический перевод в рабочий процесс релиза. - [Как перевести JSON-файлы i18n?](https://generaltranslation.com/ru/kb/translate-json-files.mdx): Переводите только строковые значения в JSON-файле локали. Ключи, не связанные с множественным числом, заполнители вроде {{name}} и теги оставляйте без изменений, но учтите, что ключи для форм множественного числа зависят от языка: например, для польского нужны inbox_few и inbox_many. Используйте инструмент или API с поддержкой формата, а затем разберите и проверьте результат перед вычиткой. - [Как перевести файлы PO и POT?](https://generaltranslation.com/ru/kb/translate-po-files.mdx): Заполните каждый msgstr, включая все формы множественного числа, которых требует заголовок Plural-Forms, а msgid, msgctxt и заполнители оставьте без изменений. Запустите msgfmt --check, чтобы проверить заголовки, количество форм множественного числа и заполнители в записях с флагом формата, а затем отдельно убедитесь, что не осталось пустых msgstr. CLI General Translation создаёт переведённый PO-файл для каждого языка на основе вашего POT-шаблона. ## Previous and next questions - Previous question: [Как перевести файлы PO и POT?](https://generaltranslation.com/ru/kb/translate-po-files.mdx) - Next question: [Как переводить контент в Payload CMS?](https://generaltranslation.com/ru/kb/translate-payload-content.mdx) ## Sitemap See the [Knowledge Base sitemap](https://generaltranslation.com/ru/kb/sitemap.md) for every article.