Cómo usar la CLI (Strings)

Controla cómo el cliente importa y exporta 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
Contraseña: ********

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
Contraseña: ********
TFA: ********

Autenticación utilizando el token de acceso de Strings

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

$ phrase projects list --access_token ACCESS_TOKEN

o usa la variable de entorno PHRASE_ACCESS_TOKEN para almacenar tu token:

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Si se activa la autenticación de 2 factores, se debe proporcionar un 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, y se utiliza el token proporcionado a través de la etiqueta o variable de entorno en su lugar. Los tokens 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 token y utilizar métodos alternativos, como pasar el token a través de la variable de entorno o una etiqueta de línea de comandos. Almacenar tokens secretos directamente en un repositorio puede ser un problema de seguridad.

Autenticación utilizando el token de acceso de la Plataforma

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

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"

Usa 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
Cargando config/locales/de.yml
Cargado config/locales/de.yml con éxito.
Subiendo config/locales/en.yml
Se ha subido config/locales/en.yml con éxito.

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
Se ha descargado de a config/locales/de.yml
Se ha descargado en a config/locales/en.yml

Compatibilidad con límite de velocidad

El cliente admite el 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 mostrará se ha superado el límite de velocidad, la descarga se reanudará en x segundos.

Comando de limpieza de cargas

El comando de limpieza de cargas se proporciona para eliminar claves que se encuentran en el proyecto pero no están contenidas en el archivo subido. Después de cargar archivos de localización, puede ser necesario eliminar todas las claves que no estén contenidas en una localización predeterminada o en alguna otra:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Opciones de formato

Varios formatos, como CSV, admiten opciones de formato adicionales durante la carga. 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 en diferentes proyectos o archivos y mejora la trazabilidad de las claves de traducción. La interfaz CLI admite el manejo de prefijos de clave para operaciones de extracción y envío.

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 NOMBRE_DE_USUARIO_O_TOKEN_DE_ACCESO \\
  -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=formato&translation_key_prefix=prefix_&filter_by_prefix=true" \\
  -u NOMBRE_DE_USUARIO_O_TOKEN_DE_ACCESO

Proxy

Si está detrás de un proxy, especifica la configuración del 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 mantener estructuras de archivos para obtener detalles sobre cómo configurar el proyecto.

Múltiples proyectos para un proyecto de localización

Cuando trabajes en un gran proyecto 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. Especifica el patrón requerido en .phrase.yml.

En lugar de definir un objetivo de extracción separado para cada localización, usa la configuración global locale_mapping combinada con el marcador de posición <locale_name>. La CLI utilizará el nombre personalizado del mapeo para la localización correspondiente y volverá al código de localización predeterminado de Phrase para todos los demás idiomas.

Ejemplo:

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

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

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

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