Utilisation de l'outil CLI (Strings)

Vous pouvez contrôler comment le client pousse et tire les fichiers en modifiant le fichier de configuration .phrase.yml.

Exemple de fichier de configuration.

Règles d'échappement et utilisation des guillemets

Lors du passage d'objets JSON sur la ligne de commande, les règles d'échappement et l'utilisation des guillemets peuvent varier en fonction du shell utilisé.

Si vous utilisez un shell Windows, mettez toute la chaîne JSON entre des guillemets doubles "" et échappez les guillemets doubles dans JSON en utilisant un caractère barre oblique inverse \. Par exemple :

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

Accès aux points de terminaison API

Le client peut être utilisé pour accéder à tous les points de terminaison API. Par exemple, pour lister tous les projets :

$ phrase projects list --access_token ACCESS_TOKEN

Authentification à l'aide des informations d’identification Phrase

Spécifiez le nom d’utilisateur avec le drapeau --username et le mot de passe sera demandé :

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

Si l'authentification à deux facteurs est activée pour l'utilisateur ou l'organisation, un jeton multifacteur valide doit être fourni via le drapeau --tfa :

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

Authentification utilisant un jeton d'accès Strings

Utilisez le drapeau --access_token pour spécifier votre jeton d’accès :

$ phrase projects list --access_token ACCESS_TOKEN

ou utilisez la variable d'environnement PHRASE_ACCESS_TOKEN pour stocker votre jeton :

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Si l'authentification à deux facteurs est activée, un jeton multifacteur valide doit être fourni via le drapeau --x_phrase_app_otp :

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

Le jeton peut également être fourni en mode interactif avec le drapeau --tfa :

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

Le jeton d'accès est lu par défaut dans le fichier de configuration .phrase.yml, mais le comportement peut être remplacé en utilisant les drapeaux ou les variables d'environnement mentionnés ; le jeton fourni via le drapeau ou la variable d’environnement est alors utilisé. Les jetons fournis par le biais de drapeaux remplacent ceux fournis par la variable d'environnement.

Lors du stockage du fichier .phrase.yml dans un référentiel de code, il est recommandé de retirer le jeton d'abord et d'utiliser d'autres méthodes, telles que le passage du jeton via l'environnement ou un flag de ligne de commande. Stocker des jetons secrets directement dans un référentiel peut être un problème de sécurité.

Authentification utilisant un jeton d'accès Platform

Les jetons d'API Platform ne sont pas acceptés directement par la CLI Strings. Les utilisateurs doivent d'abord les échanger contre un jeton d'accès produit à courte durée de vie (JWT) puis utiliser le jeton renvoyé via l'une des options suivantes :

Commandes Push et Pull

Utilisez les commandes push et pull pour charger et télécharger les fichiers de paramètres régionaux. En lieu et place des arguments de ligne de commande, les commandes Push et Pull reposent sur la configuration stockée dans le fichier de configuration .phrase.yml dans le dossier racine du projet.

Si l'option update_translations est définie sur true, la commande push écrase les traductions. La commande Pull écrase toujours les traductions dans le fichier local.

Pour supprimer automatiquement des clés dans Phrase Strings lorsqu'elles sont retirées d'un fichier source, ajouter le paramètre delete_unmentioned_keys: true à la section push du fichier de configuration .phrase.yml. Ce paramètre doit être placé au niveau push, en tant qu'élément frère de sources, et non imbriqué sous params. Ce paramètre supprime toute clé dans le projet Phrase qui est absente du fichier synchronisé. Utiliser ceci uniquement lorsque le fichier source contient toutes les clés pour le projet.

Exemple de configuration pour charger et télécharger des fichiers de paramètres régionaux d'une application Rails type :

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"

Utilisez la commande push pour charger des fichiers de paramètres régionaux dans le projet identifié par project_id correspondant au fichier de.yml et en.yml dans le dossier config/locales. S'il y a de nouvelles clés, celles-ci seront ajoutées au fichier de localisation :

$ phrase push
Uploading config/locales/de.yml
Uploaded config/locales/de.yml successfully.
Uploading config/locales/en.yml
Uploaded config/locales/en.yml successfully.

Utilisez la commande pull pour télécharger les fichiers de paramètres régionaux du projet identifié par project_id vers leurs chemins de fichiers respectifs. S’il y a de nouvelles clés, celles-ci seront ajoutées au projet :

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

Prise en charge de la limite de débit

Le client prend en charge la limite de débit pour les téléchargements des paramètres régionaux. Lorsque la limite de débit est atteinte, le client attend que la limite de débit ait expiré et poursuit le téléchargement des paramètres régionaux ultérieurement. Le client affiche Limite de débit dépassée. Le téléchargement reprendra dans x secondes.

Commande Upload cleanup

La commande Upload cleanup est fournie pour supprimer les clés qui se trouvent dans le projet, mais qui ne sont pas contenues dans le fichier chargé. Après avoir poussé les fichiers de paramètres régionaux, il peut être nécessaire de supprimer toutes les clés qui ne sont pas contenues dans des paramètres régionaux par défaut ou dans d’autres paramètres régionaux :

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Options de format

Plusieurs formats, comme le format CSV, prennent en charge des options de format supplémentaires pendant le chargement. Accédez à ces options en préfixant les options par --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

Préfixe de clé de traduction

Un préfixe de clé de traduction empêche les collisions de clés entre différents projets ou fichiers et améliore la traçabilité des clés de traduction. L'interface CLI prend en charge la gestion des préfixes de clé pour les opérations pull et push.

Exemple de configuration du fichier phrase.yml :

phrase:
  access_token: jeton_d_accès
  file_format: yml
  push:
    sources:
      -
        file: path/to/your/file.yml
        project_id: Identifiant_du_projet
        params:
          locale_id: en
          translation_key_prefix: préfixe_
  pull:
    targets:
      -
        file: path/to/your/file.yml
        project_id: Identifiant_du_projet
        params:
          translation_key_prefix: préfixe_
          filter_by_prefix: true

Exemple de commandes 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/projets/:project_Identifiant/paramètre linguistique/:Identifiant/téléchargement?file_format=format&translation_key_prefix=prefix_&filter_by_prefix=true\" \\
  -u USERNAME_OR_ACCESS_TOKEN

Proxy

Si derrière un proxy, spécifiez les paramètres proxy à l'aide de la variable d'environnement HTTPS_PROXY :

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

Plusieurs fichiers de localisation pour un projet

Utilisez un fichier pour chacun des paramètres régionaux dans un projet. Si des outils ou un framework obligent à utiliser plusieurs fichiers, reportez-vous à la section Conserver les structures des fichiers pour plus de détails sur la façon de configurer le projet.

Plusieurs projets pour un projet de localisation

Lorsque vous travaillez sur un grand projet de localisation, répartissez les traductions sur plusieurs projets. Configurez l’ILC pour travailler avec plusieurs fichiers de localisation pour un même projet de localisation.

Options de format

Certains formats de fichiers permettent de spécifier des options de format pour disposer d'un plus grand contrôle sur la syntaxe des fichiers. Spécifiez les options de format dans le fichier de configuration .phrase.yml.

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

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

Configuration pour les projets Android

Android n'utilise pas les codes de langue ISO standard comme motif de fichier. Spécifiez le motif requis dans .phrase.yml.

Au lieu de définir une cible de tirage distincte pour chaque paramètre linguistique, utiliser le paramètre global locale_mapping combiné avec l'espace réservé <locale_name>. Le CLI utilisera le nom Personnalisé du mappage pour le paramètre linguistique correspondant et reviendra au code de paramètre linguistique Phrase par défaut pour toutes les autres langues.

Exemple :

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

  # Mapper les paramètres linguistiques Phrase vers des noms de répertoire spécifiques à Android
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # Le fichier source est la langue par défaut, mappé sur 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          Identifiant_paramètre linguistique: en-US # Doit correspondre au paramètre linguistique source dans Phrase

  pull:
    targets:
      # utiliser l'espace réservé <locale_name> qui sera remplacé par le mappage
      - file: ./app/src/main/res/<locale_name>/Strings.xml