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

Примітка: Цей файл конфігурації може працювати лише з новим CLI (v3).

Вступ

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

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

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

$ crowdin init

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

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

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

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

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

"project_id": "projectId"                     #відкрийте налаштування проекту та перейдіть до розділу API 
"api_token": "personal-access-token"          #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"preserve_hierarchy": true

"files": [
  {
    "source": "/locale/en/folder1/[0-2].txt",                                       #фільтр вихідних файлів
    "translation": "/locale/%two_letters_code%/folder1/%original_file_name%"        #де зберігаються переклади
  },
  {
    "source": "/locale/en/folder2/[0-2].txt",
    "translation": "/locale/%two_letters_code%/folder2/%original_file_name%"
  }
]

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

$ crowdin upload sources

Завантажити переклади з Crowdin і покласти їх в правильні директорії:

$ crowdin download

Облікові дані API зі змінних оточення

Ви можете завантажити облікові дані API зі змінної оточення, наприклад:

"project_id_env": "CROWDIN_PROJECT_ID"
"api_token_env": "CROWDIN_PERSONAL_TOKEN"
"base_path_env": "CROWDIN_BASE_PATH"
"base_url_env": "CROWDIN_BASE_URL"

При змішуванні api_token і project_id мають перевагу:

"project_id_env": "CROWDIN_PROJECT_ID"      # Низький пріоритет
"api_token_env": "CROWDIN_PERSONAL_TOKEN"   # Низький пріоритет
"base_path_env": "CROWDIN_BASE_PATH"        # Низький пріоритет
"base_url_env": "CROWDIN_BASE_PATH"         # Низький пріоритет
"project_id": "projectId"                   # Високий пріоритет
"api_token": "personal-access-token"        # Високий пріоритет
"base_path": "/project-base-path"           # Високий пріоритет
"base_url": "https://crowdin.com"           # Високий пріоритет

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

Файл crowdin.yaml містить опис ресурсів управління та облікових даних API (project_id, api_token, base_path, base_url). Це означає, що небезпечно, поміщати цей файл в репозиторій коду, так як ключ 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”.

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

Збігається з будь-яким рядком рекурсивно (включаючи підпапки). Зверніть увагу, що ви можете використовувати ** і в шаблонах 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 Enterprise дозволяє відображати власні мови, щоб вони стали відомими у ваших проектах.

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

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

  1. Відкрийте Налаштування проекту і перейдіть до розділу Експорт.
  2. Натисніть Відображення мови, щоб додати власні коди для цільових мов вашого проекту.

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

Якщо вам потрібно перейменувати файл з перекладами після експорту, це легко зробити за допомогою параметра ` translation_replace`.

Наприклад, якщо файл має назву “en_strings.po”, його можна перейменувати на “strings.po”. Для цього додайте новий параметр (на тому ж рівні, що і параметр перекладу) в файл конфігурації (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_id": "projectId"                     #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"          #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен >Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"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_id": "projectId"                     #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"          #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"
"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%",
    "type": "properties"
  }
]

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

Параметр update_option — необов’язковий. Якщо він не заданий, переклади для змінених рядків будуть втрачені. Корисно для виправлення помилок і незначних змін у вихідних рядках.

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

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

  • update_as_unapproved - зберегти переклади змінених рядків і видалити затвердження цих перекладів, якщо вони існують
  • update_without_changes — зберегти переклади і затвердження перекладів змінених рядків

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

"project_id": "projectId"                     #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"          #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"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 Вказує, чи потрібно перекладати атрибути тегів. Доступні значення: 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_id": "projectId"                   #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"        #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"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_quotes. Допустимі значення: 0, 1, 2, 3. Значення за замовчуванням 3.

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

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

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

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

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

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

"project_id": "projectId"                   #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"        #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"files": [
  {
    "source": "/en/strings.properties",
    "translation": "/%two_letters_code%/%original_file_name%",
    "escape_quotes": 1,
    "translate_content": 0,
    "escape_special_characters": 0
  }
]

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

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

"project_id": "projectId"                   #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"        #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"files": [
  {
    "source": "/*.csv",
    "translation": "/%two_letters_code%/%original_file_name%",
    # Specifies 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_id": "projectId"                   #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"        #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"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_id": "projectId"                   #відкрийте налаштування проекту та перейдіть до розділу API
"api_token": "personal-access-token"        #відкрийте налаштування проекту та перейдіть до розділу API & SSO > Новий токен > Створити токен
"base_path": "/project-base-path"
"base_url": "https://crowdin.com"

"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": "/project-base-path"
"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

За замовчуванням всі мови експортуються. Якщо вам потрібно експортувати будь-які конкретні мови, скористайтеся опцією export_languages, щоб їх позначити.

Приклад:

"base_path": "/project-base-path"
"export_languages": [                                   
    "ru", 
    "uk", 
    "ja"
  ]
"files": [
  {
    "source" : "/resources/en/*.json",
    "translation" : "/resources/%two_letters_code%/%original_file_name%"
  }
]

Використовуйте єдиний файл конфігурації для інтеграції VCS та CLI

Бувають випадки, коли для одного проекту необхідно використовувати інтеграцію VCS та CLI. В основному в такій ситуації потрібно мати два окремі файли конфігурації: один - для інтеграції в VCS, інший - для CLI. Однак можна використовувати один файл конфігурації в обох випадках.

Оскільки файл конфігурації інтеграції VCS не містить облікових даних project_id і api_token, необхідні для CLI, ви можете передати їх безпосередньо команді, використовуючи такі параметри: -i/--project-id, -T/-token. Крім того, для цієї мети можна використовувати змінні середовища.

Як результат, ваша команда для завантаження перекладів через CLI буде виглядати наступним чином:

$ crowdin download -i {your-project-id} -T {your-token}

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

Вам потрібна допомога з API Crowdin або у вас є питання? Зв’язатись з командою підтримки.

Дивись також

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