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

Примітка: Цей файл конфігурації може працювати лише з новим 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 allows you to map your own languages to be recognizable in your projects.

Припустимо, папки з вашими Локаль називаються ‘en’, ‘uk’, ‘fr’, ‘de’. Всі вони можуть бути представлені заповнювачем %two_letters_code%. У той же час у вас є папка ‘zh_CH’. To make it work with Crowdin without changes in your project, you can set up Language Mapping. Також ви можете перевизначити коди мов для інших наповнювачів, таких як%android_code%, %locale% і т.д.

You can set up Language Mapping either via the user interface (UI) or by adding a languages_mapping section to your file set. We recommend setting up a language mapping via UI since it eliminates the need for duplicating the languages_mapping parameter for each file filter, but of course, you can choose the option that works best for you.

To set up Language Mapping via UI, follow these steps:

  1. Open the Project settings > General tab and scroll down to the Export section.
  2. Натисніть Відображення мови, щоб додати власні коди для цільових мов вашого проекту.

To set up Language Mapping in your configuration file, add the languages_mapping section to your file set as shown below.

Sample configuration:

"files": [
  {
    "source" : "/locale/en/**/*.po",
    "translation" : "/locale/%two_letters_code%/**/%original_file_name%",
    "languages_mapping" : {
      "two_letters_code" : {
        "uk" : "ukr",
        "pl" : "pol"
      }
    }
  }
]

Mapping format is the following: “crowdin_language_code” : “code_you_use”. Check the full list of Crowdin language codes that can be used for mapping.

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

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

For example, if the file is named “en_strings.po” it can be renamed to “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"                     #open project settings and go to API section
"api_token": "personal-access-token"          #open profile settings and go to API & SSO > New Token > create Token
"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"                     #open project settings and go to API section
"api_token": "personal-access-token"          #open profile settings and go to API & SSO > New Token > create Token
"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"                     #open project settings and go to API section
"api_token": "personal-access-token"          #open profile settings and go to API & SSO > New Token > create Token
"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. If no options specified, the uploaded translations will not be imported even if they are equal with the source strings and will not be approved.

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

  • -l, --language=language_code - defines the language translations that should be uploaded to Crowdin. За замовчуванням переклади завантажуються на всі цільові мови проекту. (мовні коди Crowdin)
  • --[no-]import-eq-suggestions - defines whether to add translation if it is equal to source string in Crowdin project
  • --[no-]auto-approve-imported - automatically approves uploaded translations

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

translate_content
необов'язковий
bool Defines whether to translate texts placed inside the tags.
Acceptable values are: 0 or 1. Значення за замовчуванням 1.
translate_attributes
необов'язковий
bool Defines whether to translate tags' attributes.
Acceptable values are: 0 or 1. Значення за замовчуванням 1.
content_segmentation
необов'язковий
bool Defines whether to split long texts into smaller text segments.
Acceptable values are: 0 or 1. Значення за замовчуванням 1.
Важливо! Ця опція вимикає можливість завантажувати існуючі переклади для файлів XML, коли увімкнена.
translatable_elements
необов'язковий
масив Це масив рядків, де кожен елемент є елементом XPath для DOM, який повинен бути імпортований.
Приклад шляху: /path/to/node or /path/to/attribute[@attr]
Увага! Якщо задані, параметри translate_content і translate_attributes не враховуються при імпорті.

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

"project_id": "projectId"                   #open project settings and go to API section
"api_token": "personal-access-token"        #open profile settings and go to API & SSO > New Token > create Token
"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"                   #open project settings and go to API section
"api_token": "personal-access-token"        #open profile settings and go to API & SSO > New Token > create Token
"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"                   #open project settings and go to API section
"api_token": "personal-access-token"        #open profile settings and go to API & SSO > New Token > create Token
"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"                   #open project settings and go to API section
"api_token": "personal-access-token"        #open profile settings and go to API & SSO > New Token > create Token
"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"                   #open project settings and go to API section
"api_token": "personal-access-token"        #open profile settings and go to API & SSO > New Token > create Token
"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

Each time translations are committed the default message is shown “New translations {fileName} ({languageName})”. You can use commit_message parameter to add Git tags (e.g. to skip builds).

Приклад:

"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

За замовчуванням всі мови експортуються. If you need to export some specific languages, use export_languages parameter to specify them.

Приклад:

"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

There are cases when it’s necessary to use VCS integration and CLI for one project. Mostly, in this kind of situation, you’d need to have two separate configuration files, one for VCS integration and another for CLI. However, there is a possibility to use a single configuration file for both cases.

Since the VCS integration configuration file doesn’t contain project_id and api_token credentials that are required for CLI, you can pass them directly in the command using the following parameters: -i/--project-id, -T/--token. Alternatively, you may use environment variables for this purpose.

As a result, your command for downloading translations via CLI will look like the following:

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

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

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

Дивись також

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