Форматы

Выберите обработчик файлов, который переведёт текст и сохранит нужную приложению структуру.

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

Lingo.dev использует обработчик формата, чтобы выбрать текст для перевода и собрать результат. Выбирайте обработчик с учётом назначения файла. Каталог Rails и спецификация OpenAPI могут иметь одно и то же расширение .yml, но перевод всех строк в них вызовет разные проблемы: корневой ключ локали в Rails нужно изменить, а идентификаторы операций API — оставить без изменений.

Найдите свой формат #

ИсточникТип обработчикаСправочник
Каталог JSON с вложенной структуройjsonJSON
JSON с контекстными комментариямиjsoncJSONC
Каталог YAMLyamlYAML
YAML с одним корневым ключом локалиyaml-root-keyYAML с корневым ключом локали
Статический модуль локали на TypeScripttypescriptTypeScript
Статический массив локали на PHPphpPHP
Документ MarkdownmdMarkdown
Markdown с компонентами JSXmdxMDX
Документ MarkdocmarkdocMarkdoc
OpenAPI 3.x в формате YAMLyaml-openapiOpenAPI
XML-файл ресурсов AndroidandroidAndroid
Пакет ресурсов приложения FlutterflutterFlutter ARB
Таблица строк Applexcode-stringsApple strings
Файл plist Apple с ресурсами форм множественного числаxcode-stringsdictApple stringsdict
Каталог Apple с несколькими локалямиxcode-xcstringsКаталоги строк Apple
Каталог Gettext POpoGettext
Документ XLIFF для обмена даннымиxliffXLIFF
Субтитры SubRipsrtSubRip
Обычный текст с построчным переводомtxtОбычный текст
Документ или фрагмент HTMLhtmlHTML
CSV-таблица с отдельным столбцом для каждой локалиcsvCSV
Набор ресурсов в формате Java propertiespropertiesJava properties
Выбранные поля Payload CMSpayloadPayload

В справочных материалах описаны доступные обработчики файлов и их ограничения при извлечении и восстановлении содержимого. CLI и GitHub App поддерживают перечисленные выше 22 настроенных типа, кроме Payload. HTML определяется по .html и .htm. В результате нетронутые части исходного файла сохраняются, а у явно заданного элемента <html> для lang устанавливается целевая локаль. Нужный вариант YAML или формат Android укажите явно в конфигурации репозитория. Как и каталоги строк Apple, CSV хранит все локали в исходном файле. В кратком руководстве по CLI показана работа с одним файлом — от настройки до получения результата. Раздел GitHub описывает управляемый рабочий процесс для репозитория.

Существующие подключения к поставщикам выбирают и записывают контент по собственным контрактам интеграции.

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

Храните версию исходного файла вместе с её переводами #

При инкрементальном переводе текущий исходный файл сравнивается с предыдущей версией и используется соответствующий ей существующий перевод. Это позволяет сохранить принятые формулировки в неизменённых сообщениях и перевести новые или изменённые.

Ключи позволяют точно сопоставлять сообщения: checkout.title и account.title могут содержать одинаковый английский текст, но сохранять разные переводы. При сопоставлении также учитываются позиции в массивах, номера блоков субтитров, позиции строк в обычном тексте и структура документа. Перемещение элемента или перестройка переведённого документа может изменить соответствие. Поэтому храните переводы вместе с той версией исходного файла, на основе которой они созданы.

Для большинства форматов создаётся отдельный файл для каждой целевой локали. Каталоги строк Apple вместо этого объединяют локали в исходном файле. Артефакт Payload или каталог строк также может содержать лишь часть целевых значений. Проверяйте сами записи перевода, а не только наличие файла.

Управляйте выбором текста и результатом отдельно #

Исключить текст из перевода можно по-разному. Заблокированное значение каталога берётся из исходного файла, сохраняемое — из существующего перевода, а игнорируемое может не попасть в результат. Доступные настройки зависят от формата и интерфейса вызова.

Используйте область видимости ключей в CLI для JSON/JSONC, YAML, YAML с корневым ключом локали, PHP и TypeScript. При частичном обновлении существующие формулировки перевода вне выбранной области сохраняются. Но обработка записей, которые есть только в исходном файле, и позиций в массивах зависит от формата. Проверяйте результат целиком, сверяясь со справочником по формату.

У метаданных контекста тоже есть свои особенности. Комментарий @context в JSONC описывает следующее строковое значение. В ARB @message.description описывает соответствующее сообщение. В Gettext msgctxt позволяет различать сообщения и задаёт контекст. Обычные комментарии могут сохраняться при сборке результата, но не служить инструкциями для перевода. Аннотации @src и @orphan в React относятся к рабочему процессу сопровождения каталога.

Получив файл, загрузите его в системе, которая с ним работает. Проверьте не только смысл перевода, но и выбранную локаль, переменные, формы множественного числа, ссылки и защищённые данные. Завершить эту работу помогут руководства для веб-приложений, нативных ресурсов и статического контента.