Using the CLI (Strings)

Controla cómo el cliente importa y exporta los archivos editando el archivo de configuración .phrase.yml.

Archivo de configuración de muestra.

Uso de comillas y reglas de escape

Al pasar objetos JSON por la línea de comandos, el uso de comillas y reglas de escape puede variar según el shell utilizado.

Si usas un shell de Windows, encierra toda la cadena JSON entre comillas dobles "" y escapa las comillas dobles dentro de JSON usando una barra invertida \. Por ejemplo:

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

Acceso a los extremos de la API

Se puede usar el cliente para acceder a los extremos de la API. Por ejemplo, a la lista de todos los proyectos:

$ phrase projects list --access_token ACCESS_TOKEN

Autenticación mediante credenciales de Phrase

Especifica el nombre de usuario con la etiqueta --username. Se solicitará la contraseña:

$ phrase projects list --username user@example.com
Password: ********

Si se activa la autenticación de 2 factores para el usuario u organización, se debe proporcionar un identificador único (token) multifactor válido a través de la etiqueta --tfa:

$ phrase projects list --username user@example.com --tfa
Password: ********
TFA: ********

Autenticación mediante token de acceso

Usa la etiqueta --access_token para especificar el token de acceso:

$ phrase projects list --access_token ACCESS_TOKEN

o usa la variable de entorno PHRASE_ACCESS_TOKEN para almacenar el token.

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Si se activa autenticación de 2 factores, se debe proporcionar un identificador único (token) multifactor válido a través de la etiqueta --x_phrase_app_otp:

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

El token también se puede proporcionar en modo interactivo con la etiqueta --tfa:

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

El token de acceso se lee por defecto del archivo de configuración .phrase.yml, pero se puede anular el comportamiento utilizando las etiquetas o variables de entorno mencionadas para que, en su lugar, utilice el token proporcionado a través de la etiqueta o variable de entorno. Los token proporcionados a través de etiquetas anulan los proporcionados mediante la variable de entorno.

Al almacenar el archivo .phrase.yml en un repositorio de código, se recomienda eliminar primero el identificador único (token) y usar métodos alternativos, como pasar el identificador único (token) por el entorno o marcarlo en línea de comandos. Almacenar tokens secretos directamente en un repositorio puede ser un problema de seguridad.

Comandos push y pull

Usa los comandos push y pull para cargar y descargar archivos de localización. En lugar de argumentos de línea de comandos, los comandos push y pull se basan en la configuración almacenada en el archivo de configuración .phrase.yml de la carpeta principal del proyecto.

Si push tiene la opción update_translations marcada como verdadera, sobrescribe las traducciones. En cambio, pull siempre sobrescribe las traducciones en el archivo local.

Configuración de ejemplo para cargar y descargar archivos de localización de una aplicación típica de 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"

Use el comando push para cargar archivos de localización en el proyecto identificado por project_id que coincida con los archivos de.yml y en.yml en la carpeta «config/locales». Si hay claves nuevas, se agregarán al archivo de localización:

$ phrase push
Uploading config/locales/de.yml
Uploaded config/locales/de.yml successfully.
Uploading config/locales/en.yml
Uploaded config/locales/en.yml successfully.

Usa el comando pull para descargar archivos de localización del proyecto identificado por project_id a sus respectivas rutas de archivo. Si hay claves nuevas, se agregarán al proyecto:

$ phrase pull
Downloaded de to config/locales/de.yml
Downloaded en to config/locales/en.yml

Compatibilidad con límite de velocidad

El cliente admite un límite de velocidad para las descargas de localizaciones. Cuando se alcanza el límite de velocidad, el cliente espera hasta que haya expirado el límite de velocidad y continúa descargando localizaciones después. El cliente avisará con un mensaje similar al siguiente: Se ha superado el límite de velocidad. La descarga se reanudará en X segundos.

Comando Uploads cleanup

El comando Uploads cleanup se proporciona para eliminar claves que se encuentran en el proyecto pero no están en el archivo cargado. Después de cargar archivos de localización, es posible que haga falta eliminar todas las claves que no estén en una localización predeterminada o en alguna otra:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Opciones de formato

Algunos formatos, como CSV, admiten opciones de formato adicionales al cargar. Accede a estas opciones poniendo el prefijo --format_options a las opciones:

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

Prefijo clave de traducción

El prefijo de clave de traducción evita las colisiones de claves entre diferentes proyectos o archivos y mejora la trazabilidad de las claves de traducción. La interfaz CLI admite el manejo de prefijos clave tanto para operaciones pull como push.

Configuración de ejemplo del archivo Phrase.yml:

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

Ejemplo de comandos Curl:

curl "https://api.phrase.com/v2/projects/:project_id/uploads?translation_key_prefix=prefix_" \
  -u USERNAME_OR_ACCESS_TOKEN \
  -X POST \
  -F archivo=@/ruta/a/mi/archivo.formato \
  -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

Proxy

Si está detrás de un proxy, especifica la configuración proxy utilizando la variable de entorno HTTPS_PROXY:

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

Múltiples archivos de localización para un proyecto

Usa un archivo por cada localización en un proyecto. Si las herramientas o marcos obligan a usar varios archivos, consulta el artículo sobre cómo mantener estructuras de archivos para ver cómo configurar el proyecto.

Múltiples proyectos para un proyecto de localización

Cuando trabajes en un proyecto grande de localización, distribuye las traducciones en varios proyectos. Configura la CLI para trabajar con múltiples archivos de localización para un proyecto de localización.

Opciones de formato

Algunos formatos de archivo permiten especificar opciones de formato para un mayor control sobre la sintaxis de los archivos. Indica las opciones de formato en el archivo de configuración .phrase.yml:

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

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

Configuración para proyectos de Android

Android no usa los códigos de idioma estándares ISO como patrón de archivo. Indica el patrón requerido en .phrase.yml.

Especifica cada localización explícitamente en el archivo .phrase.yml. Este ejemplo muestra una configuración .phrase.yml con inglés como idioma predeterminado, una localización alemana y una localización regional alemana para el alemán austriaco:

phrase:
  access_token: ACCESS_TOKEN
  project_id: PROJECT_ID
  file_format: xml
  pull:
    targets:
    - file: ./app/src/main/res/values/strings.xml
      params:
        file_format: xml
        # Unique locale id for English
        locale_id: LOCALE_ID
    - file: ./app/src/main/res/values-de/strings.xml
      params:
        file_format: xml
        # Unique locale id for German
        locale_id: LOCALE_ID
    - file: ./app/src/main/res/values-de-rAU/strings.xml
      params:
        file_format: xml
        # Unique locale id for Austrian
        locale_id: LOCALE_ID
  push:
    sources:
    - file: ./app/src/main/res/values/strings.xml
      params:
        file_format: xml
        locale_id: LOCALE_ID
    - file: ./app/src/main/res/values-de/strings.xml
      params:
        file_format: xml
        locale_id: LOCALE_ID
    - file: ./app/src/main/res/values-de-rAU/strings.xml
      params:
        file_format: xml
        locale_id: LOCALE_ID