Usando a CLI (Strings)

Controle como o cliente executa push e pull nos arquivos editando o arquivo de configuração .phrase.yml.

Amostra de arquivo de configuração.

Regras de escape e uso de aspas

Ao passar objetos JSON na linha de comando, o uso de regras e aspas de escape pode variar de acordo com o shell usado.

Se você estiver usando um shell do Windows, inclua toda a string JSON em aspas duplas "" e faça o escape de aspas duplas no JSON usando um caractere \ da barra invertida. Por exemplo:

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

Acessar endpoints da API

O cliente pode ser usado para acessar todos os endpoints da API. Por exemplo, para listar todos os projetos:

$ phrase projects list --access_token ACCESS_TOKEN

Autenticação usando credenciais do Phrase

Especifique o nome de usuário com a marca --username e a senha será solicitada:

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

Se a autenticação de dois fatores estiver ativada para o usuário ou organização, um token de múltiplos fatores válido deverá ser fornecido através do sinal --tfa:

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

Autenticação usando o token de acesso Strings

Use a marca --access_token para especificar seu token de acesso:

$ phrase projects list --access_token ACCESS_TOKEN

ou use a variável de ambiente PHRASE_ACCESS_TOKEN para armazenar seu token:

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Se a autenticação de dois fatores estiver ativada, um token de múltiplos fatores válido deve ser fornecido por meio da marca --x_phrase_app_otp:

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

O token também pode ser fornecido em modo interativo com a marca --tfa:

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

O token de acesso é lido a partir do arquivo de configuração .phrase.yml por padrão, mas o comportamento pode ser substituído usando as marcas ou variáveis de ambiente mencionadas, e o token fornecido por meio da marca ou variável de ambiente é usado em vez disso. Os tokens fornecidos por meio de marcas substituem os tokens fornecidos por meio da variável de ambiente.

Ao armazenar o arquivo .phrase.yml em um repositório de código, é recomendável remover o token primeiro e usar métodos alternativos, como passar o token pela variável de ambiente ou por uma marca de linha de comando. Armazenar tokens secretos diretamente em um repositório pode ser um problema de segurança.

Autenticação usando o token de acesso da Plataforma

Tokens da API da Plataforma não são aceitos diretamente pelo CLI do Strings. Os usuários devem primeiro trocá-los por um token de acesso de produto de curta duração (JWT) e então usar o token retornado através de uma das seguintes opções:

Push e pull

Use os comandos push e pull para fazer upload e download de arquivos locais. Em vez de argumentos de linha de comando, push e pull contam com a configuração armazenada no arquivo de configuração .phrase.yml na pasta raiz do projeto.

Se o push tiver a opção update_translations definida como true, o push substituirá as traduções. Pull sempre substitui as traduções no arquivo local.

Exemplo de configuração para fazer upload e download de arquivos locais de um aplicativo típico 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 o comando push para fazer upload de arquivos locais ao projeto identificado pelo project_id correspondente ao arquivo de.yml e en.yml na pasta config/locales. Se houver novas chaves, elas serão adicionadas ao arquivo de localização:

$ phrase push
Fazendo upload de config/locales/de.yml
Uploaded config/locales/de.yml com sucesso.
Fazendo upload de config/locales/en.yml
Uploaded config/locales/en.yml com sucesso.

Use o comando pull para baixar arquivos locais do projeto identificado pelo project_id para seus caminhos de arquivos respectivos. Se houver novas chaves, elas serão adicionadas ao projeto:

$ phrase pull
Baixado de para config/locales/de.yml
Baixado en para config/locales/en.yml

Suporte ao limite de taxa

O cliente suporta o limite de taxa para downloads locais. Quando o limite de taxa é atingido, o cliente espera até que o limite de taxa expire e continua baixando os locais depois. O cliente exibe limite de taxa excedido, o download será retomado em x segundos.

Limpeza de upload

O comando de limpeza de uploads é fornecido para excluir chaves que estão no projeto, mas não estão contidas no arquivo enviado por upload. Após enviar arquivos locais, pode ser necessária a exclusão de todas as chaves que não estão contidas em um local padrão ou em outro local:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Opções de formato

Vários formatos, como CSV, suportam opções de formato adicionais durante o upload. Acesse estas opções prefixando as opções com --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

Prefixo da chave de tradução

Um prefixo de chave de tradução evita colisões de chaves em diferentes projetos ou arquivos e melhora a rastreabilidade das chaves de tradução. A interface CLI suporta o manuseio de prefixos de chaves para operações de pull e push.

Exemplo de configuração do arquivo phrase.yml:

phrase:
  access_token: access_token
  file_format: yml
  push:
    sources:
      -
        file: caminho/para/seu/arquivo.yml
        project_id: project_id
        params:
          locale_id: en
          translation_key_prefix: prefix_
  pull:
    targets:
      -
        file: caminho/para/seu/arquivo.yml
        project_id: project_id
        params:
          translation_key_prefix: prefix_
          filter_by_prefix: true

Exemplo 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=@/caminho/para/meu/arquivo.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

Se estiver atrás de um proxy, especifique as configurações de proxy usando a variável de ambiente HTTPS_PROXY:

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

Vários arquivos de localização para um projeto

Use um arquivo para cada local em um projeto. Se Ferramentas ou frameworks forçar o uso de vários arquivos, consulte Manter estruturas de arquivos para obter detalhes sobre como configurar o projeto.

Vários projetos para um projeto de localização

Ao trabalhar em um grande projeto de localização, distribua traduções em vários projetos. Configure o CLI para trabalhar com vários arquivos de localização para um projeto de localização.

Opções de formato

Alguns formatos de arquivo permitem especificar opções de formato para controlar melhor a sintaxe do arquivo. Especifique as opções de formato no arquivo de configuração .phrase.yml:

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

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

Configuração para projetos Android

O Android não usa os códigos de idioma ISO padrão como padrão de arquivo. Especifique o padrão necessário em .phrase.yml.

Em vez de definir um alvo de pull separado para cada local, use a configuração global locale_mapping combinada com o marcador de posição <locale_name>. A CLI usará o nome personalizado do mapeamento para o local correspondente e recorrerá ao código de local padrão do Phrase para todos os outros idiomas.

Exemplo:

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

  # Mapeie os locais do Phrase para nomes de diretório específicos do Android
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # O arquivo de origem é o idioma padrão, mapeado para 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # Deve corresponder ao local de origem no Phrase

  pull:
    targets:
      # Use o marcador de posição <locale_name> que será substituído pelo mapeamento
      - file: ./app/src/main/res/<locale_name>/strings.xml