Cómo usar la 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 usando el identificador único (token) de acceso de Strings

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 el identificador único (token) primero y usar métodos alternativos, como pasar el identificador único (token) a través del entorno o una marca de línea de comandos. Almacenar identificadores únicos (token) secretos directamente en un repositorio puede ser un problema de seguridad.

Autenticación usando el identificador único (token) de acceso de la Plataforma

Los identificadores únicos (token) de la API de la Plataforma no son aceptados directamente por la CLI de Strings. Los usuarios deben primero intercambiarlos por un identificador único (token) de acceso de producto de corta duración (JWT) y luego usar el identificador único (token) devuelto a través de una de las siguientes opciones:

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.

Para eliminar automáticamente claves en Phrase Strings cuando se eliminan de un archivo fuente, agregue el parámetro delete_unmentioned_keys: true a la sección push del archivo de configuración .phrase.yml. Este parámetro debe colocarse en el nivel push, como un elemento hermano de sources, no anidado bajo params. Este parámetro elimina cualquier clave en el proyecto Phrase que esté ausente del archivo sincronizado. Usar esto solo cuando el archivo fuente contenga todas las claves para el proyecto.

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 de clave de traducción

Un prefijo de clave de traducción evita 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 de clave tanto para operaciones pull como push.

Ejemplo de configuración del archivo 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

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 file=@/path/to/my/file.format \
  -F file_format=format \
  -F locale_id=locale_id

curl \"https://api.Phrase.com/v2/proyectos/:project_id/localizaciones/:id/descargar?file_formato=file_formato&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.

En lugar de definir un meta de extracción independiente para cada localización, usar el ajuste global locale_mapping combinado con el marcador de posición <locale_name>. La CLI usará el nombre Personalizar del mapeo para la localización correspondiente y recurrirá al código de localización de Phrase predeterminado para todos los demás idiomas.

Ejemplo:

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

  # Mapear localizaciones de Phrase a nombres de directorio específicos de Android
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # El archivo fuente es el idioma predeterminado, mapeado a 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # Debe coincidir con la localización fuente en Phrase

  pull:
    targets:
      # usar el marcador de posición <locale_name> que será reemplazado por el mapeo
      - file: ./app/src/main/res/<locale_name>/Strings.xml