Using the CLI (Strings)

Controlla il modo in cui il client esegue push e pull dei file modificando il file di configurazione .phrase.yml.

File di configurazione di esempio.

Regole di escape e utilizzo delle virgolette

Quando si passano oggetti JSON sulla riga di comando, le regole di escape e l’utilizzo di virgolette potrebbero variare in base alla shell utilizzata.

Se utilizzi una shell di Windows, racchiudi l'intera stringa JSON tra virgolette doppie "" ed esegui il comando di escape sulle virgolette doppie all’interno di JSON utilizzando il carattere \. Ad esempio:

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

Accesso agli endpoint API

Il client può essere utilizzato per accedere a tutti gli endpoint API. Ad esempio, per elencare tutti i progetti:

$ phrase projects list --access_token ACCESS_TOKEN

Autenticazione tramite credenziali di Phrase

Specifica il nome utente con il flag --username e verrà richiesta la password:

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

Se l'autenticazione a due fattori è attivata per l'utente o l'organizzazione, deve essere fornito un token multifattore valido tramite il flag --tfa:

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

Autenticazione tramite token di accesso

Usa il flag --access_token per specificare il tuo token di accesso:

$ phrase projects list --access_token ACCESS_TOKEN

oppure usa la variabile d’ambiente PHRASE_ACCESS_TOKEN per memorizzare il tuo token:

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Se l'autenticazione a due fattori è attiva, è necessario fornire un token multifattore valido tramite il flag --x_phrase_app_otp:

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

Il token può essere fornito anche in modalità interattiva con il flag --tfa:

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

Il token di accesso viene letto dal file di configurazione .phrase.yml per impostazione predefinita, ma il comportamento può essere sovrascritto utilizzando i flag o le variabili env menzionate. In tal caso, viene invece utilizzato il token fornito tramite la variabile d'ambiente o il flag. I token forniti tramite flag sostituiscono i token forniti tramite la variabile d'ambiente.

Quando si archivia il file .phrase.yml in un archivio di codice, si consiglia di rimuovere prima il token e usare metodi alternativi, come il passaggio del token nell’ambiente o segnalare una riga di comando. Archiviare i token segreti direttamente in un archivio può essere un problema di sicurezza.

Push e pull

Usa i comandi push e pull per caricare e scaricare i file della lingua. Invece degli argomenti della riga di comando, push e pull si affidano alla configurazione archiviata nel file di configurazione .phrase.yml nella cartella root del progetto.

Se push ha l'opzione update_translations impostata su true, push sovrascrive le traduzioni. Pull sovrascrive sempre le traduzioni nel file locale.

Esempio di configurazione per caricare e scaricare file della lingua di una tipica applicazione di 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 il comando push per caricare file della lingua nel progetto identificato da project_id corrispondente al file de.yml ed en.yml nella cartella config/locales. Se ci sono nuove chiavi, queste verranno aggiunte al file di localizzazione:

$ 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 il comando pull per scaricare file della lingua dal progetto identificato da project_id ai rispettivi percorsi di file. Se ci sono nuove chiavi, queste verranno aggiunte al progetto:

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

Limite d’uso

Il client supporta il limite d’uso per i download con impostazioni locali. Quando viene raggiunto il limite, il client attende la scadenza del limite e continua successivamente a scaricare le impostazioni locali. Il client mostra il limite d’uso superato, il download riprenderà tra x secondi.

Pulizia dei caricamenti

Il comando di pulizia dei caricamenti viene fornito per eliminare le chiavi che si trovano nel progetto ma non sono contenute nel file caricato. Dopo aver eseguito il push dei file della lingua, potrebbe essere necessario eliminare tutte le chiavi che non sono contenute in una lingua predefinita o in altre lingue:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Format options

Diversi formati, come CSV, supportano opzioni di formato aggiuntive durante il caricamento. Accedi a queste opzioni prefissando le opzioni con --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

Prefisso delle chiavi di traduzione

Un prefisso chiave traduzione previene conflitti di chiavi tra progetti o file diversi e migliora la tracciabilità delle chiavi di traduzione. L'interfaccia della CLI supporta la gestione dei prefissi chiave sia per le operazioni pull che push.

Esempio di configurazione del file 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

Esempio di comandi 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

Proxy

Se dietro un proxy, specifica le impostazioni del proxy utilizzando la variabile d'ambiente HTTPS_PROXY:

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

Più file di localizzazione per un solo progetto

Usa un solo file per ogni lingua in un progetto. Se gli strumenti o il framework costringono all’utilizzo di più file, vedi manutenzione delle strutture dei file per dettagli su come configurare il progetto.

Progetti multipli per un solo progetto di localizzazione

Se lavori su un grande progetto di localizzazione, distribuisci le traduzioni su più progetti. Configura la CLI per lavorare con più file di localizzazione per un solo progetto di localizzazione.

Opzioni di formato

Alcuni formati di file consentono di specificare le opzioni di formato per un maggiore controllo della sintassi dei file. Specifica le opzioni di formato nel file di configurazione .phrase.yml:

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

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

Configurazione per progetti Android

Android non usa i codici di linguaggio ISO standard come modello di file. Specifica il modello richiesto in .phrase.yml.

Specifica esplicitamente ogni lingua nel file .phrase.yml. Questo esempio mostra una configurazione .phrase.yml con l'inglese come lingua predefinita, una lingua tedesca e una lingua di regione tedesca per tedesco 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