Crowdin CLI использует файл конфигурации YAML, который содержит описание ресурсов для управления: файлы, которые будут загружены в Crowdin, и местоположения соответствующих переводов.
Чтобы использовать Crowdin CLI, вы должны сначала сгенерировать файл конфигурации, а затем запустить инструмент. По умолчанию Crowdin CLI ищет файл конфигурации с именем crowdin.yaml (поэтому вам не нужно указывать имя файла, если оно не отличается от crowdin.yaml).
Для создания файла конфигурации выполните следующую команду:
$ crowdin generateПравильный файл конфигурации Crowdin CLI YAML имеет следующую структуру, поэтому убедитесь, что вы заполнили всю необходимую информацию:
Смотрите статью Настройка интеграции API, чтобы узнать, где найти учетные данные вашего проекта.
Типичный файл конфигурации YAML выглядит примерно так:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #can be found in your project settings page
"base_path": "/home/office/source-code"
"files": [
{
"source" : "/resources/en/*.json", #source files filter
"translation" : "/resources/%two_letters_code%/%original_file_name%" #where translations are stored
}
]Примечание: В Windows, если вы используете разделитель каталогов в стиле Windows, он должен быть удвоен в соответствии с синтаксисом YAML:
{
"source" : "\\resources\\en\\*.json",
"translation" : "\\resources\\%two_letters_code%\\%original_file_name%"
}Чтобы запустить этот файл конфигурации и загрузить исходные файлы на Crowdin, стоит всего лишь выполнить команду:
$ crowdin upload sourcesСкачать переводы из Crowdin и положить их в правильные директории:
$ crowdin downloadВы можете загрузить учетные данные API из переменной окружения, например:
"api_key_env": CROWDIN_API_KEY
"project_identifier_env": CROWDIN_PROJECT_ID
"base_path_env": CROWDIN_BASE_PATHЕсли смешано, api_key и project_identifier имеют приоритет:
"api_key_env": CROWDIN_API_KEY # Низкий приоритет
"project_identifier_env": CROWDIN_PROJECT # Низкий приоритет
"base_path_env": CROWDIN_BASE_PATH # Низкий приоритет
"api_key": "xxx" # Высокий приоритет
"project_identifier": "yyy" # Высокий приоритет
"base_path": "zzz" # Высокий приоритетФайл crowdin.yaml содержит описание ресурсов для управления и учетные данные API (api_key, project_identifier, base_path). Это означает, что небезопасно, помещать этот файл в репозиторий кода, так как ключ API будет доступен другим пользователям. Crowdin CLI поддерживает 2 типа конфигурационных файлов: + описание ресурсов для управления, находящихся в каталоге проекта, + учетные данные API, вероятно, находящихся в $HOME/.crowdin.yaml
*Примечание: **Учетные данные API из файла конфигурации.crowdin.yaml* имеет более высокий приоритет, чем учетные данные из каталога проекта (* crowdin.yaml *).
Если вам нужно запустить команду с пользовательскими учетными данными (например, upload sources) то выполните следующую команду:
$ crowdin upload sources --identity 'path-to-user-credentials-file'Но если файл пользовательских учетных данных находится в $HOME/.crowdin.yaml, вы можете просто запустить:
$ crowdin upload sourcesПриведенный выше пример конфигурации имеет атрибуты ‘source’ и ‘translation’, которые содержат стандартные постановочные знаки (также известные как универсальные шаблоны) для упрощения работы с несколькими файлами.
Вот шаблоны, которые вы можете использовать:
* (звездочка)
Этот постановочный знак соответствует любому символу в имени файла или папки. Если вы указали ‘*.json’, будут включены все файлы с именем “messages.json”, “about_us.json” и любой другой файл с расширением “.json”.
**** (удвоенная звездочка)
Совпадает с любой строчкой рекурсивно (включая подпапки). Обратите внимание, что вы можете использовать *** * как в исходном тексте, так и в шаблонах перевода. При использовании *** *** в шаблоне перевода он всегда будет содержать подпуть из источника для определенного файла. Например, вы можете использовать источник: ‘/en/ ** /*.po ‘для рекурсивной загрузки всех файлов *.po в Crowdin. Шаблон перевода должен указываться следующим образом: ‘/%two_letters_code%/**/%original_file_name%’.
? (вопросительный знак)
Соответствует любому одному символу.
[set]
Соответствует любому символу в диапазоне. Используется аналогично диапазонам символов в Regexp, включая указание отрицания ([^a-z]).
** (Обратный слэш)
Экранирует следующий метасимвол.
В crowdin cli можно использовать следующие заполнители для внесения соответствующих переменных в результирующее имя файла:
| Название | Описание |
|---|---|
| %language% | Название языка (напр. Русский) |
| %two_letters_code% | Код языка ISO 639-1 (напр. ru) |
| %three_letters_code% | Код языка ISO 639-2/T (напр. rus) |
| %locale% | Локаль (напр. ru-RU) |
| %locale_with_underscore% | Локаль (напр. ru_RU) |
| %original_file_name% | Исходное имя файла |
| %android_code% | Идентификатор языка в Android используемый в названиях «values-» директорий |
| %osx_code% | Локаль OS X, используемая для названий *.lproj" директорий |
| %original_path% | Используйте имена родительских папок в проекте Crowdin для создания пути к файлу в полученном пакете |
| %file_extension% | Исходное расширение файла |
| %file_name% | Имя файла без расширения |
Вы также можете указать полный путь к файлам в архиве, поставив косую черту (/) в начале шаблона.
Шаблон translation может выглядеть следующим образом: “/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%”.
Структура файлов и папок на локальном компьютере:
- base_path
|
|-- folder
| |
| |-- 1.xml
| |-- 1.txt
| |-- 123.txt
| |-- 123_test.txt
| |-- a.txt
| |-- a1.txt
| |-- crowdin?test.txt
| |-- crowdin_test.txt
|
|-- 1.xml
|-- 1.txt
|-- 123.txt
|-- 123_test.txt
|-- a.txt
|-- a1.txt
|-- crowdin?test.txt
|-- crowdin_test.txt
|-- 3.txt
Пример 1. Использование постановочных знаков в пути к исходным файлам:
#........конфигурация вашего проекта........
"files" : [
{
"source" : "/**/?[0-9].txt", #upload a1.txt, folder/a1.txt
"translation" : "/**/%two_letters_code%_%original_file_name%"
},
{
"source" : "/**/*\\?*.txt", #upload crowdin?test.txt, folder/crowdin?test.txt
"translation" : "/**/%two_letters_code%_%original_file_name%"
},
{
"source" : "/**/[^0-2].txt", #upload 3.txt, folder/3.txt, a.txt, folder/a.txt (ignore 1.txt, folder/1.txt)
"translation" : "/**/%two_letters_code%_%original_file_name%"
}
]Пример 2. Использование постановочных знаков для игнорирования файлов:
#........конфигурация вашего проекта........
"files": [
{
"source" : "/**/*.*", #upload all files that the base_path contains
"translation" : "/**/%two_letters_code%_%original_file_name%",
"ignore" : [
"/**/%two_letters_code%_%original_file_name%", #ignore the translated files
"/**/?.txt", #ignore 1.txt, a.txt, folder/1.txt, folder/a.txt
"/**/[0-9].txt", #ignore 1.txt, folder/1.txt
"/**/*\\?*.txt", #ignore crowdin?test.txt, folder/crowdin?test.txt
"/**/[0-9][0-9][0-9].txt", #ignore 123.txt , folder/123.txt
"/**/[0-9]*_*.txt" #ignore 123_test.txt, folder/123_test.txt
]
}
]Довольно часто программные проекты имеют собственные имена для каталогов локали. Crowdin CLI позволяет отображать ваши собственные языки, чтобы быть узнаваемыми для Crowdin.
Предположим, папки с вашими локалями называются ‘en’, ‘uk’, ‘fr’, ‘de’. Все они могут быть представлены заполнителем %two_letters_code%. В то же время у вас имеется папка ‘zh_CH’. Чтобы заставить это работать с Crowdin CLI без изменений в вашем проекте, вы можете добавить раздел languages_mapping к вашему набору файлов.
Пример конфигурации:
#........конфигурация вашего проекта........
"files" : [
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/**/%original_file_name%",
"languages_mapping" : {
"two_letters_code" : {
"ru" : "ros",
"uk" : "ukr"
}
}
}
]Формат разметки следующий:“crowdin_language_code” : “нужный_языковый_код”. Ознакомьтесь с полным списком языковых кодов Crowdin, которые можно использовать для разметки.
Вы также можете переопределить языковые коды для других заполнителей таких как %android_code%, %locale% и тд.
Если вам нужно переименовать файл с переводами после экспорта, это легко сделать с помощью параметра ` translation_replace`.
Например, если файл называется «strings_en.xml», его можно переименовать в «strings.xml». Для этого добавьте новый параметр (на том же уровне, что и параметр перевода) в файл конфигурации (crowdin.yaml):
"files" : [
{
"source" : "/locale/**/en_*.po",
"translation" : "/locale/**/%two_letters_code%_%original_file_name%",
"translation_replace": {
"en_" : ""
}
}
]В этом случае «_en» будет просто удален из имени файла.
Иногда появляются файлы и каталоги, которые вам не нужно переводить в Crowdin. В таких случаях в файл конфигурации вашего проекта могут быть добавлены локальные правила для каждого файла.
"files": [
{
"source" : "/**/*.properties",
"translation" : "/**/%file_name%_%two_letters_code%.%file_extension%",
"ignore" : [
"/test/file.properties",
"/example.properties"
]
},
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/**/%original_file_name%",
"ignore" : [
"/locale/en/templates",
"/locale/en/workflow"
]
}
]Если файл CSV содержит переводы для всех целевых языков, вы должны указать соответствующие коды языков в схеме.
Пример файла CSV:
identifier,source_phrase,context,Ukrainian,Russian,French
ident1,Source 1,Context 1,,,
ident2,Source 2,Context 2,,,
ident3,Source 3,Context 3,,,Пример файла конфигурации:
"files" : [
{
"source" : "multicolumn.csv",
"translation" : "multicolumn.csv",
"first_line_contains_header" : true,
"scheme" : "identifier,source_phrase,context,uk,ru,fr"
}
]"preserve_hierarchy": trueПример использования конфигурации с использованием параметра preserve_hierarchy:
"project_identifier": "test"
"api_key": "KeepTheAPIkeySecret"
"base_url": "https://api.crowdin.com"
"base_path": "/path/to/your/project"
"preserve_hierarchy": true
"files" : [
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/**/%original_file_name%"
}
]По умолчанию, папки не содержащие файлов для перевода не будут созданы в Crowdin. Например:
- locale
|
|-- en
|
|-- foo.po
|-- bar.po
По умолчанию файлы проекта будут представлены в Crowdin следующим образом:
- foo.po
- bar.po
С использованием параметра preserve_hierarchy структура файлов в Crowdin будет следующей:
- en
|
|-- foo.po
|-- bar.po
Эта функция добавляет поддержку 2 дополнительных параметров в yaml файл: dest и type. Это как правило полезно для некоторых проектов, где загруженные имена должны отличаться от Crowdin, но он мог определить тип правильно. Параметр Dest позволяет задать имя файла в Crowdin.
Dest работает только для однофайловых переводовПример конфигурационного файла с обоими параметрами:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #может быть найден на странице настроек вашего проекта
"base_path": "/home/office/source-code"
"files" : [
{
"source" : "/conf/messages",
"dest" : "/messages.properties",
"translation" : "/conf/messages.%two_letters_code%",
"type" : "properties"
},
{
"source" : "/app/strings.xml",
"dest" : "/strings.xml",
"translation" : "/res/values-%android_code%/%original_file_name%"
}
]Параметр update_option является необязательным. Если он не установлен, переводы для изменённых строк будут потеряны. Рекомендуем использовать этот параметр при исправлении опечаток или незначительных изменениях в строках для перевода.
В зависимости от значения update_option используется для сохранения переводов и сохранения/удаления утверждений переводов и изменённых строк во время обновления файла.
Поддерживаемые опции: * update_as_unapproved - сохранение переводов измененных строк с удалением их утверждений, что позволит редактору утвердить перевод * update_without_changes - сохранение переводов и утверждений измененных строк
Пример конфигурационного файла с использованием параметра update_option:</p>
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #может быть найден на странице настроек вашего проекта
"base_path": "/home/office/source-code"
"files" : [
{
"source" : "/*.csv",
"translation" : "/%three_letters_code%/%file_name%.csv",
"first_line_contains_header" : true,
"scheme" : "identifier,source_phrase,translation,context",
"update_option" : "update_as_unapproved"
},
{
"source": "/**/*.xlsx",
"translation" : "/%three_letters_code%/folder/%file_name%.xlsx",
"update_option" : "update_without_changes"
}
]Команда upload translations загружает существующие переводы в Crowdin. Если параметры не указаны, загруженные переводы не будут импортированы, даже если они дублированы или совпадают с исходными строками и не будут утверждены.
Используйте следующие значения:
| translate_content необязательный | булево | Определяет, переводить ли тексты, размещенные внутри тегов. Допустимые значения: 0 или 1. По умолчанию 1. |
| translate_attributes необязательный | булево | Определяет, переводить ли атрибуты тегов. Допустимые значения: 0 или 1. По умолчанию 1. |
| content_segmentation необязательный | булево | Определяет, следует ли разбивать длинные тексты на более мелкие текстовые сегменты. Допустимые значения: 0 или 1. Значение по умолчанию 1. Важно! Эта опция отключает возможность загружать существующие переводы для файлов XML, когда включена. |
| translatable_elements необязательный | массив | Это массив строк, где каждый элемент является элементом XPath для DOM, который должен быть импортирован. Пример пути: /path/to/node or /path/to/attribute[@attr] Внимание! Если задан, параметры translate_content и translate_attributes не учитываются при импорте. |
Пример конфигурационного файла с дополнительными параметрами:
"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #может быть найден на странице настроек вашего проекта
"base_path": "/home/office/source-code"
"files" : [
{
"source" : "/app/sample1.xml",
"translation" : "/app/%locale%/%original_file_name%",
"translate_attributes" : 1,
"translate_content" : 0
},
{
"source" : "/app/sample2.xml",
"translation" : "/app/%locale%/%original_file_name%",
"translatable_elements" : [
"/content/text", # translatable texts are stored in "text" nodes of parent node "content"
"/content/text[@value]" # translatable texts are stored in "value" attribute of "text" nodes
]
}
]Определяет, будет ли одинарная кавычка экранирована другой одинарной кавычкой или обратным слешем в экспортированных переводах. Вы можете добавить опцию escape_quote для каждого файла. Допустимые значения: 0, 1, 2, 3. Значение по умолчанию 3.
Используйте следующие значения:
Экранирование специальных символов
Определяет, нужно ли экранировать специальные символы (=,:,! и #) обратной косой чертой в экспортированных переводах. Вы можете добавить параметр escape_special_characters для каждого файла.
Допустимые значения: 0, 1. По умолчанию 0.
Пример конфигурационного файла:
"project_identifier": "your-project-identifier"
"api_key”: "54e01e81--your-api-key--f6a2724a" #может быть найдено на странице настроек вашего проекта
"base_path”: "/home/office/source-code"
"files" : [
{
"source" : "/en/strings.properties",
"translation" : "/%two_letters_code%/%original_file_name%",
"escape_quotes" : 1,
"escape_special_characters: 0"
}
]"project_identifier": "test"
"api_key": "KeepTheAPIkeySecret"
"base_url": "https://api.crowdin.com"
"base_path": "/path/to/your/project"
"files" : [
{
"source" : "/*.csv",
"translation" : "/%two_letters_code%/%original_file_name%",
# Defines whether first line should be imported or it contains columns headers
"first_line_contains_header" : true,
# Used only when uploading CSV file to define data columns mapping.
"scheme" : "identifier,source_phrase,translation,context,max_length"
}
]"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #может быть найден на странице настроек вашего проекта
"base_path": "/home/website"
"files" : [
{
"source" : "/locale/en/**/*.po",
"translation" : "/locale/%two_letters_code%/LC_MESSAGES/%original_file_name%",
"languages_mapping" : {
"two_letters_code" : {
"zh-CN" : "zh_CH",
"fr-QC": "fr"
}
}
}
]"project_identifier": "your-project-identifier"
"api_key": "54e01e81--your-api-key--f6a2724a" #может быть найден на странице настроек вашего проекта
"base_path": "/home/android-app"
"files" : [
{
"source" : "/res/values/*.xml",
"translation" : "/res/values-%android_code%/%original_file_name%",
"languages_mapping" : {
"android_code" : {
"de" : "de",
"ru" : "ru"
}
}
}
]Интеграция VCS требует того же файла конфигурации, что и инструмент CLI, то есть поддерживается та же структура. Единственное отличие состоит в том, что учетные данные проекта не должны храниться в заголовке файла по соображениям безопасности. Также можно использовать два дополнительных параметра.
Каждый раз, когда переводы отправляются на слияние, по умолчанию отображается сообщение «Новые переводы {fileName} ({languageName})». Вы можете использовать параметр commit_message для добавления Git тегов, чтобы пропустить сборки, добавить тесты и многое другое.
Пример:
"base_path": "/home/office/source-code"
"commit_message": "[ci skip]"
"files": [
{
"source" : "/resources/en/*.json", #фильтр исходных файлов
"translation" : "/resources/%two_letters_code%/%original_file_name%" #местоположение хранения переводов
}
]Чтобы заменить сообщение коммита по умолчанию, используйте параметр append_commit_message со значением false. Вы также можете добавить два необязательных заполнителя: %original_file_name% и %language% чтобы использовать переменные имя файла и язык соответственно.
Пример:
"commit_message": "Fix: новый перевод %original_file_name% из Crowdin"
"append_commit_message": false
"files": [
{
"source" : "/resources/en/*.json", #фильтр исходных файлов
"translation" : "/resources/%two_letters_code%/%original_file_name%" #место хранения переводов
}
]По умолчанию все языки экспортируются. Если вам нужно экспортировать некоторые конкретные языки, используйте параметр export_languages для их указания.
Пример:
"base_path": "/home/office/source-code"
"export_languages": [
"ru",
"uk",
"ja"
]
"files": [
{
"source" : "/resources/en/*.json", #фильтр исходных файлов
"translation" : "/resources/%two_letters_code%/%original_file_name%" #место хранения переводов
}
]Нужна помощь по работе с Crowdin CLI или есть вопросы? Связаться со службой поддержки .