Форматы
Выберите обработчик файлов, который переведёт текст и сохранит нужную приложению структуру.
Файл локали — это не только слова. Ключи связывают сообщения с кодом, в плейсхолдеры подставляются значения из приложения, а структура указывает фреймворку, как загрузить результат. В документе к этому добавляются заголовки, ссылки, примеры и метаданные. При переводе файла нужно изменить язык, не потеряв эти связи.
Lingo.dev использует обработчик формата, чтобы выбрать текст для перевода и собрать результат. Выбирайте обработчик с учётом назначения файла. Каталог Rails и спецификация OpenAPI могут иметь одно и то же расширение .yml, но перевод всех строк в них вызовет разные проблемы: корневой ключ локали в Rails нужно изменить, а идентификаторы операций API — оставить без изменений.
Найдите свой формат #
| Источник | Тип обработчика | Справочник |
|---|---|---|
| Каталог JSON с вложенной структурой | json | JSON |
| JSON с контекстными комментариями | jsonc | JSONC |
| Каталог YAML | yaml | YAML |
| YAML с одним корневым ключом локали | yaml-root-key | YAML с корневым ключом локали |
| Статический модуль локали на TypeScript | typescript | TypeScript |
| Статический массив локали на PHP | php | PHP |
| Документ Markdown | md | Markdown |
| Markdown с компонентами JSX | mdx | MDX |
| Документ Markdoc | markdoc | Markdoc |
| OpenAPI 3.x в формате YAML | yaml-openapi | OpenAPI |
| XML-файл ресурсов Android | android | Android |
| Пакет ресурсов приложения Flutter | flutter | Flutter ARB |
| Таблица строк Apple | xcode-strings | Apple strings |
| Файл plist Apple с ресурсами форм множественного числа | xcode-stringsdict | Apple stringsdict |
| Каталог Apple с несколькими локалями | xcode-xcstrings | Каталоги строк Apple |
| Каталог Gettext PO | po | Gettext |
| Документ XLIFF для обмена данными | xliff | XLIFF |
| Субтитры SubRip | srt | SubRip |
| Обычный текст с построчным переводом | txt | Обычный текст |
| Документ или фрагмент HTML | html | HTML |
| CSV-таблица с отдельным столбцом для каждой локали | csv | CSV |
| Набор ресурсов в формате Java properties | properties | Java properties |
| Выбранные поля Payload CMS | payload | Payload |
В справочных материалах описаны доступные обработчики файлов и их ограничения при извлечении и восстановлении содержимого. 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 относятся к рабочему процессу сопровождения каталога.
Получив файл, загрузите его в системе, которая с ним работает. Проверьте не только смысл перевода, но и выбранную локаль, переменные, формы множественного числа, ссылки и защищённые данные. Завершить эту работу помогут руководства для веб-приложений, нативных ресурсов и статического контента.