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

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

Вступ

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

Щоб використовувати Crowdin CLI, ви повинні спочатку згенерувати файл конфігурації, а потім запустити інструмент. За замовчуванням Crowdin CLI шукає файл конфігурації з ім’ям crowdin.yaml (тому вам не потрібно вказувати ім’я файлу, якщо воно не відрізняється від crowdin.yaml).

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

$ crowdin generate

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

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

  • Заголовок файлу з обліковими даними проекту, настроюваннями та інформацією про доступ
  • Один елемент масиву файлів, який описує набір вихідних файлів і файлів перекладу, якими ви будете керувати
  • Обов’язкові поля в масиві файлів: Source, яке визначає фільтри для вихідних файлів, і Translation з вказівками, де зберігати перекладені файли або де шукати переклади, які у вас вже є, якщо ви хочете завантажити їх під час налаштування CLI

Дивіться статтю Налаштування інтеграції API, щоб дізнатися, де знайти облікові дані вашого проекту.

Створення простого файлу конфігурації

Типовий файл конфігурації YAML виглядає приблизно так:

"project_identifier": "your-project-identifier" "api_key": "54e01e81--your-api-key--f6a2724a"                 #можна знайти в налаштуваннях вашого проекту > API tab "base_path": "/home/office/source-code"

"files": [
  {
    "source" : "/resources/en/*.json",                                          #фільтр вихідних файлів
    "translation" : "/resources/%two_letters_code%/%original_file_name%"        #де зберігаються переклади
  }
]

Примітка: У 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 підтримує 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’, які містять стандартні постановочні знаки (також відомі як універсальні шаблони) для спрощення роботи з декількома файлами.

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

* (зірочка)

Являє собою всякий символ в імені файлу або каталогу. If you specify a “*.json” it will include all files like “messages.json”, “about_us.json” and anything that ends with “.json”.

*** (подвійна зірочка)

Збігається з будь-яким рядком рекурсивно (включаючи підпапки). Зверніть увагу, що ви можете використовувати ** і в шаблонах source і translation. При використанні ** в шаблоні translation, він завжди буде містити підшлях з source для конкретного файлу. Наприклад, ви можете використовувати source: ‘/en/**/*.po’, щоб завантажити в Crowdin все рекурсивні файли *.po. Шаблон перекладу буде ‘/%two_letters_code%/**/%original_file_name%’.

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

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

[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

Приклад 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" : "/**/*.*", #завантажте всі файли, які містять base_path "translation" : "/**/%two_letters_code%_%original_file_name%", "ignore" : [ "/**/%two_letters_code%_%original_file_name%", #ігноруйте перекладені файли "/**/?.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 дозволяє відображати ваші власні мови.

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

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

Також ви можете перевизначити коди мов для інших наповнювачів, таких як%android_code%, %locale% і т.д.

Ви можете налаштувати відображення мови для кожної з цільових мов вашого проекту через інтерфейс користувача (UI):

  1. Перейдіть: Налаштування проекту, розділ Експорт.
  2. Натисніть Відображення мови.
  3. Виберіть необхідну мову, заповнювач і додайте власний код.

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

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

Якщо ваш CSV-файл містить стовпці, потрібно пропустити при імпорті, використовуйте none для таких стовпців в схемі, наприклад:

"scheme" : "identifier,source_phrase,context,uk,none,ru,none,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 працює тільки для окремих файлів, і якщо ви використовуєте його, файл конфігурації також містить точок serve_hierarchy в значенні true.

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

"project_identifier": "your-project-identifier" "api_key": "54e01e81--your-api-key--f6a2724a"                 #можна знайти у вашому проекті settings > API tab "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%"
  }
]

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

Параметр 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"                 #можна знайти в налаштуваннях вашого проекту > API tab "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"                 #можна знайти в налаштуваннях вашого проекту > API tab "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",             # тексти, які перекладаються, що зберігаються в вузлах "text" батьківського вузла "content"
      "/content/text[@value]"      # тексти, які перекладаються, зберігаються в атрибуті "value" вузлів "text"
    ]
  }
]

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

Визначає, чи буде одинарна лапка екранована інший одинарною лапкою або зворотнім слешем в експортованих перекладах. You can add escape_quotes per-file option. Допустимі значення: 0, 1, 2, 3. Значення за замовчуванням 3.

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

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

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

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

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

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

"project_identifier": "your-project-identifier" "api_key": "54e01e81--your-api-key--f6a2724a"                 #можна знайти в налаштуваннях вашого проекту > API tab "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"                 #можна знайти у вашому проекті settings > API tab "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"                 #можна знайти у вашому проекті settings > API tab "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: New translations %original_file_name% from 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. Якщо вам потрібно експортувати будь-які конкретні мови, використовуйте параметр 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%"        #де зберігаються переклади
  }
]

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

Need help working with Crowdin CLI or have any questions? Зв’язатись з командою підтримки.

Дивись також

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