Utilizzo della 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 utilizzando il token di accesso Strings

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 memorizza il file .phrase.yml in un archivio di codice, è consigliabile rimuovere prima il token e utilizzare metodi alternativi, come passare il token attraverso l'ambiente o un flag da riga di comando. Memorizzare token segreti direttamente in un archivio può essere un problema di sicurezza.

Autenticazione utilizzando il token di accesso della piattaforma

Piattaforma API token non sono accettati direttamente dalla CLI di Strings. Gli utenti devono prima scambiarli per un token di accesso prodotto a breve termine (JWT) e poi utilizzare il token restituito attraverso una delle seguenti opzioni:

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 della chiave di traduzione

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

Esempio di configurazione del file phrase.yml:

phrase:
  access_token: access_token
  file_format: yml
  push:
    sources:
      -
        file: percorso/verso/il/tuo/file.yml
        project_id: project_id
        params:
          locale_id: en
          translation_key_prefix: prefix_
  pull:
    targets:
      -
        file: percorso/verso/il/tuo/file.yml
        project_id: project_id
        params:
          translation_key_prefix: prefix_
          filter_by_prefix: true

Esempi 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=@/percorso/verso/mio/file.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 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.

Invece di definire un target di pull separato per ogni locale, usa l'impostazione globale locale_mapping combinata con il <locale_name> segnaposto. La CLI utilizzerà il nome personalizzato dalla mappatura per il corrispondente locale e ricadrà sul codice locale predefinito di Phrase per tutte le altre lingue.

Esempio:

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

  # Mappa i locali di Phrase ai nomi delle directory specifici per Android
  locale_mapping:
    en-US: valori
    de-DE: valori-de-rDE
    fr-FR: valori-fr

  push:
    sources:
      # Il file sorgente è la lingua predefinita, mappato su 'valori'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # Deve corrispondere al locale sorgente in Phrase

  pull:
    targets:
      # Usa il segnaposto <locale_name> che sarà sostituito dalla mappatura
      - file: ./app/src/main/res/<locale_name>/strings.xml