Файл конфігурації

Примітка:Якщо ви використовуєте стару версію Crowdin CLI (0.5.5 або менше) дивіться Crowdin Github для повної інформації.

Вступ

Crowdin CLI використовує файл конфігурації YAML, який містить опис ресурсів для управління: файли, які будуть завантажені в Crowdin, і розташування відповідних перекладів.

Щоб використовувати Crowdin CLI, ви повинні спочатку згенерувати файл конфігурації, а потім запустити інструмент. By default, Crowdin CLI looks for a configuration file named crowdin.yaml (so you don’t have to specify the file name unless it’s different from crowdin.yaml).

Для створення файлу конфігурації виконайте наступну команду:

$ crowdin generate

Структура файлу конфігурації

Правильний файл конфігурації Crowdin CLI YAML має наступну структуру, тому переконайтеся, що ви заповнили всю необхідну інформацію:

  • Заголовок файлу з обліковими даними проекту, настроюваннями та інформацією про доступ
  • Один елемент масиву файлів, який описує набір вихідних файлів і файлів перекладу, якими ви будете керувати
  • Required fields in the files array: Source that defines filters for the source files and Translation with instructions on where to store the translated files or where to look for translations you already have if you want to upload them while setting up the CLI

Дивіться статтю Налаштування інтеграції 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 зі змінної оточення, наприклад:

"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"                        # Високий пріоритет

Поділ конфігурації проекту і облікових даних API

Файл crowdin.yaml містить опис ресурсів для управління і облікові дані API (api_key, project_identifier, base_path). Це означає, що небезпечно, поміщати цей файл в репозиторій коду, так як ключ API буде доступний іншим користувачам. Crowdin CLI supports 2 types of configuration files:

  • a description of the resources to manage, residing in the project directory
  • API credentials, probably residing in $HOME/.crowdin.yaml

Note: API credentials from .crowdin.yaml configuration file are of higher priority than credentials from project directory(crowdin.yaml).

Якщо вам потрібно запустити команду до призначених для користувача обліковими даними (наприклад, upload sources) то виконайте наступну команду:

$ crowdin upload sources --identity 'path-to-user-credentials-file'

Але якщо файл призначених для користувача облікових даних знаходиться в $HOME/.crowdin.yaml, ви можете просто запустити:

$ crowdin upload sources

Загальні налаштування

Наведений вище приклад конфігурації має атрибути ‘source’ і ‘translation’, які містять стандартні постановочні знаки (також відомі як універсальні шаблони) для спрощення роботи з декількома файлами.

Ось шаблони, які ви можете використовувати:

* (asterisk)

Represents any character in file or directory name. If you specify a “*.json” it will include all files like “messages.json”, “about_us.json” and anything that ends with “.json”.

** (doubled asterisk)

Збігається з будь-яким рядком рекурсивно (включаючи підпапки). Note that you can use ** in both source and translation patterns. When using ** in the translation pattern, it will always contain sub-path from source for a certain file. For example, you can use source: ‘/en/**/*.po’ to upload all *.po files to Crowdin recursively. The translation pattern will be ‘/%two_letters_code%/**/%original_file_name%’.

? (знак питання)

Відповідає будь-якому одному символу.

[set]

Matches any single character in a set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

\ (зворотний слеш)

Пропускає такий метасимвол.

Заповнювачі

У Crowdin CLI можна використовувати наступні наповнювачі для внесення відповідних змінних в результуюче ім’я файлу:

Ім'я Опис
%language% Назва мови (напр. Українська)
%two_letters_code% Код мови ISO 639-1 (напр. uk)
%three_letters_code% Код мови ISO 639-2/T (напр. ukr)
%locale% Локаль (напр. uk-UA)
%locale_with_underscore% Локаль (напр. uk-UA)
%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%”.

Використання символів підстановки (wildcards)

Структура файлів і папок на локальному комп’ютері:

- 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

Example 1. Usage of wildcards in the source path:

# ........конфігурація вашого проекту........
"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%" } ]

Example 2. Usage of wildcards for ignoring files:

# ........конфігурація вашого проекту........

"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 allows you to map your own languages.

Припустимо, папки з вашими Локаль називаються ‘en’, ‘uk’, ‘fr’, ‘de’. Всі вони можуть бути представлені заповнювачем %two_letters_code%. У той же час у вас є папка ‘zh_CH’. Щоб змусити це працювати з Crowdin CLI без змін у вашому проекті, ви можете додати розділ languages_mapping до вашого набору файлів.

Формат розмічування є таким: “код_мови_Crowdin” : “ваш_код_мови”. Ознайомтеся з повним списком мовних кодів Crowdin, які можна використовувати для розмітки.

You can also override language codes for other placeholders like %android_code%, %locale%, etc.

You can set up Language Mapping for any of your project’s target languages via the user interface (UI):

  1. Go to the Project Settings, Export section.
  2. Click Language Mapping.
  3. Choose the necessary language, placeholder, and add custom code.

Перейменування файлу перекладу

Якщо вам потрібно перейменувати файл з перекладами після експорту, це легко зробити за допомогою параметра ` 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» буде просто видалений з імені файлу.

Ігнорування файлів і каталогів

From time to time there are files and directories you don’t need to translate in Crowdin. In such cases, local per-file rules can be added to the config file in your project.

"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 містить переклади для всіх цільових мов, ви повинні вказати відповідні коди мов в схемі.

Приклад файлу 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%" } ]

By default, directories that do not contain any files for translation will not be created in Crowdin. For example:

- 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.

Note! The dest parameter only works for single files, and if you use it, the configuration file should also include the preserve_hierarchy parameter with true value.

Приклад конфігураційного файлу з обома параметрами:

"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" "preserve_hierarchy": true

"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%"
  }
]

Оновлення змінених рядків

The parameter update_option is optional. If it is not set, translations for changed strings will be lost. Useful for typo fixes and minor changes in source strings.

Залежно від значення update_option використовується для збереження перекладів і збереження/видалення затверджень перекладів і змінених рядків під час оновлення файлу.

Використовуйте наступні значення:

  • update_as_unapproved - preserve translations of changed strings and remove validations of those translations if they exist
  • update_without_changes - preserve translations and validations of changed strings

Приклад конфігураційного файлу з використанням параметра update_option:</p>

"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" : "/*.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. Якщо параметри не зазначені, завантажені перекази не будуть імпортовані, навіть якщо вони дубльовані або збігаються з вихідними рядками і не будуть затверджені.

Використовуйте наступні значення:

  • -l, –language = language_code - визначає мовні переклади, які повинні бути завантажені в Crowdin. За замовчуванням переклади завантажуються на всі цільові мови проекту. (мовні коди Crowdin)
  • –[no-]import-duplicates - визначає, чи додавати переклад, якщо в проекті Crowdin вже є такий же переклад
  • –[no-]import-duplicates - визначає, чи додавати переклад, якщо рядок дорівнює вихідному в проекті Crowdin
  • –[no-]auto-approve-imported - автоматично затверджувати завантажені переклади

Розширені можливості пошуку для XML-файлів

translate_content
необов'язковий
bool Визначає, чи перекладати тексти, розміщені всередині тегів. Доступні значення: 0 або 1. Значення за замовчуванням 1.
translate_attributes
необов'язковий
bool Defines whether to translate tags' attributes. Доступні значення: 0 або 1. Значення за замовчуванням 1.
content_segmentation
необов'язковий
bool Визначає, чи слід розбивати довгі тексти на більш дрібні текстові сегменти. Доступні значення: 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"           #can be found in your project settings page "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
    ]
  }
]

Екранування лапок в форматі .properties

Визначає, чи буде одинарна лапка екранована інший одинарною лапкою або зворотнім слешем в експортованих перекладах. Ви можете додати опцію escape_quote для кожного файлу. Допустимі значення: 0, 1, 2, 3. Значення за замовчуванням 3.

Використовуйте наступні значення:

  • 0 - не екранувати одинарні лапки
  • 1 - екранувати одинарні лапки іншою одинарною лапкою
  • 2 - екранувати одинарні лапки зворотнім слешем
  • 3 - екранувати одинарні лапки іншою одинарною лапкою тільки в рядках, що містять змінні ( {0} )

Екранування спеціальних символів
Визначає, чи потрібно екранувати спеціальні символи (=,:,! і #) зворотною косою скобкою в експортованих перекладах. Ви можете додати параметр escape_special_characters для кожного файлу.

Допустимі значення: 0, 1. Значення за замовчуванням 0.

  • 0 - не екранувати спеціальні символи
  • 1 - екранувати спеціальні символи зворотною косою скобкою

Приклад конфігураційного файлу:

"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" : "/en/strings.properties",
    "translation" : "/%two_letters_code%/%original_file_name%",
    "escape_quotes" : 1,
    "escape_special_characters: 0"
  }
]

Приклади конфігурації

Завантаження файлів CSV через API

"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"
  }
]

Проект GetText

"project_identifier": "your-project-identifier" "api_key": "54e01e81--your-api-key--f6a2724a"           #can be found in your project settings page "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"
      }
    } } ]

Проект Android

"project_identifier": "your-project-identifier" "api_key": "54e01e81--your-api-key--f6a2724a"           #can be found in your project settings page "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

Інтеграція VCS вимагає того ж файлу конфігурації, що і інструмент CLI, тобто підтримується та ж структура. Єдина відмінність полягає в тому, що облікові дані проекту не повинні зберігатися в заголовку файлу з міркувань безпеки. Також можна використовувати два додаткові параметри.

Параметр повідомлення злиття для інтеграції VCS

Кожен раз, коли переклади відправляються на злиття, за замовчуванням відображається повідомлення «Нові переклади {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%"        #місце зберігання перекладів
  }
]

Параметр експорту мов для інтеграції VCS

By default, all the languages are exported. If you need to export some specific languages, use export_languages paramenter to specify them.

Приклад:

"base_path": "/home/office/source-code" "export_languages": [ "ru", "uk", "ja" ] "files": [
  {
    "source" : "/resources/en/*.json",                                          #фільтр вихідних файлів
    "translation" : "/resources/%two_letters_code%/%original_file_name%"        #місце зберігання перекладів
  }
]

Потрібна допомога

Need help working with Crowdin CLI or have any questions? Contact Support Team.

Дивись також

Ця стаття була корисною?