Использование CLI (Strings)

Контролируйте, как клиент загружает и извлекает файлы, редактируя файл конфигурации .phrase.yml.

Образец файла конфигурации.

Правила экранирования и использование кавычек

При передаче объектов JSON в командной строке правила экранирования и использование кавычек могут варьироваться в зависимости от используемой оболочки.

Если используется оболочка Windows, заключите всю строку JSON в двойные кавычки "" и экранируйте двойные кавычки в JSON, используя символ обратной косой черты \. Например:

phrase locales create --project_id PROJECT123 --data "{\"name\":\"French\", \"code\":\"fr\"}" --access_token TOKEN123123

Доступ к конечным точкам API

Клиент может быть использован, чтобы получить доступ ко всем конечным точкам интерфейса приложений API. Например, для списка всех проектов:

$ phrase projects list --access_token ACCESS_TOKEN

Аутентификация с использованием учетных данных Phrase

Укажите имя пользователя, пометив его --username, и будет запрошен пароль:

$ phrase projects list --username user@example.com
Пароль: ********

Если для пользователя или организации активирована двухфакторная аутентификация, необходимо предоставить действительный многофакторный токен через пометку --tfa:

$ phrase projects list --username user@example.com --tfa
Пароль: ********
TFA: ********

Аутентификация с использованием токена доступа Strings

Используйте пометку --access_token, чтобы указать свой токен доступа:

$ phrase projects list --access_token ACCESS_TOKEN

или используйте переменную среды PHRASE_ACCESS_TOKEN для хранения вашего токена:

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Если двухфакторная аутентификация активирована, необходимо указать действительный многофакторный токен через пометку --x_phrase_app_otp:

$ phrase projects list --access_token ACCESS_TOKEN --x_phrase_app_otp PASSWORD

Токен также может быть предоставлен в интерактивном режиме с пометкой --tfa:

$ phrase projects list --access_token ACCESS_TOKEN --tfa
TFA: ********

Токен доступа по умолчанию считывается из файла конфигурации .phrase.yml, но поведение можно переопределить, используя упомянутые пометки или переменные среды, и вместо него будет использован токен, предоставленный через пометку или переменную среды. Токены, предоставленные через пометки, переопределяют токены, предоставленные через переменную среды.

При хранении файла .phrase.yml в кодовом репозитории рекомендуется сначала удалить токен и использовать альтернативные методы, такие как передача токена через переменную среды или пометку командной строки. Хранение секретных токенов непосредственно в репозитории может быть проблемой безопасности.

Аутентификация с использованием токена доступа Platform

Токены API платформы не принимаются напрямую CLI Strings. Пользователи должны сначала обменять их на токен доступа к продукту с коротким сроком действия (JWT) и затем использовать возвращенный токен через один из следующих вариантов:

Push и pull

Используйте команды push и pull, чтобы загрузить и скачать файлы языковых стандартов. Вместо аргументов командной строки push и pull полагаются на конфигурацию, хранящуюся в файле конфигурации .phrase.yml в корневой папке проекта.

Если в push установлен параметр update_translations на true, push перезаписывает переводы. Pull всегда перезаписывает переводы в локальном файле.

Пример конфигурации для загрузки и скачивания файлов языковых стандартов типичного приложения Rails:

phrase:
  access_token: "ACCESS_TOKEN"
  project_id: "PROJECT_ID"
  file_format: "yml"
  push:
    sources:
      - file: "./config/locales/<locale_name>.yml"
  pull:
    targets:
      - file: "./config/locales/<locale_name>.yml"

Используйте команду push, чтобы загрузить файлы языковых стандартов в проект, обозначенный project_id, как файл de.yml и en.yml в папке config/locales. Если появятся новые ключи, они будут добавлены в файл локализации:

$ phrase push
Загрузка config/locales/de.yml
Файл config/locales/de.yml успешно загружен.
Загрузка config/locales/en.yml
Файл config/locales/en.yml успешно загружен.

Используйте команду pull, чтобы скачать файлы языковых стандартов из проекта, обозначенного project_id, по их соответствующим путям файлов. Если появятся новые ключи, они будут добавлены в проект:

$ phrase pull
Скачано de в config/locales/de.yml
Скачано en в config/locales/en.yml

Поддержка лимита ставок

Клиент поддерживает лимит ставок для скачивания языковых стандартов. При достижении лимита ставки клиент ждет истечения лимита ставки и после этого продолжает скачивать языковые стандарты. Клиент показывает, что лимит ставки превышен, загрузка возобновится через х секунд..

Очистка загрузок

Команда очистки загрузок предназначена для удаления ключей, которые найдены в проекте, но не содержатся в загруженном файле. После отправки файлов языковых стандартов может потребоваться удаление всех ключей, которые не содержатся в языковом стандарте по умолчанию или каких-либо других языковых стандартах:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Параметры формата

Несколько форматов, например CSV, поддерживают дополнительные параметры формата во время загрузки. Получите доступ к этим параметрам, указав --format_options:

phrase uploads create \\
--project_id PROJECT_ID \\
--file ./en.csv \\
--file_format csv \\
--locale_mapping ‘{“en”:3, “de”:2}’ \\
--format_options ‘{“key_index”:1}’ \
--access token YOUR_ACCESS_TOKEN

Префикс ключа перевода

Префикс ключа перевода предотвращает коллизии ключей в разных проектах или файлах и улучшает отслеживаемость ключей перевода. Интерфейс CLI поддерживает обработку префиксов ключей как для операций извлечения, так и для операций отправки.

Пример конфигурации файла phrase.yml:

phrase:
  access_token: access_token
  file_format: yml
  push:
    sources:
      -
        file: path/to/your/file.yml
        project_id: project_id
        params:
          locale_id: en
          translation_key_prefix: prefix_
  pull:
    targets:
      -
        file: path/to/your/file.yml
        project_id: project_id
        params:
          translation_key_prefix: prefix_
          filter_by_prefix: true

Пример команд Curl:

curl "https://api.phrase.com/v2/projects/:project_id/uploads?translation_key_prefix=prefix_" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F file=@/path/to/my/file.format \
  -F file_format=format \
  -F locale_id=locale_id

curl "https://api.phrase.com/v2/projects/:project_id/locales/:id/download?file_format=file_format&translation_key_prefix=prefix_&filter_by_prefix=true" \
  -u USERNAME_OR_ACCESS_TOKEN

Прокси

Если используется прокси-сервер, задайте настройки прокси, используя переменную среды HTTPS_PROXY:

export HTTPS_PROXY=https://user:password@host:port

Несколько файлов локализации для одного проекта

Используйте в проекте один файл на каждый языковой стандарт. Если инструменты или рамки вынуждают использовать несколько файлов, см. раздел «Поддержка файловых структур», чтобы узнать, как настроить проект.

Несколько проектов для одного проекта локализации

При работе над крупным проектом локализации распределите переводы по нескольким проектам. Настройка CLI для работы с несколькими файлами локализации для одного проекта локализации.

Параметры формата

Некоторые форматы файлов позволяют задавать параметры формата для усиления контроля над синтаксисом файлов. Укажите параметры формата в файле конфигурации .phrase.yml:

phrase:
  pull:
    targets:
    - file: file.xml
      params:
        format_options:
          convert_placeholder: true

  push:
    sources:
    - file: file.csv
      params:
        format_options:
          column_separator: ";"

Конфигурация для проектов на базе Android

Android не использует стандартные коды языка ISO в качестве шаблона файла. Укажите требуемый шаблон в .phrase.yml.

Вместо определения отдельной цели для каждого языкового стандарта, используйте глобальную настройку locale_mapping, комбинируя с заполнителем <locale_name>. CLI будет использовать пользовательское имя из сопоставления для соответствующего языкового стандарта и вернется к коду локали по умолчанию для всех других языков.

Например:

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: "xml"

  # Сопоставить локали Phrase с именами каталогов, специфичными для Android
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # Исходный файл является языком по умолчанию, сопоставленным с 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          языковой стандарт_идентификатор: en-US # Должен совпадать с исходным языковым стандартом в Phrase

  pull:
    targets:
      # Используйте заполнитель <locale_name>, который будет заменен на соответствие
      - файл: ./app/src/main/res/<locale_name>/strings.xml