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
Mot de passe : ********

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
Mot de passe : ********
TFA : ********

Authentification utilisant le 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 et le jeton fourni via le drapeau ou la variable d'environnement est utilisé à la place. 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 d'abord le jeton et d'utiliser des méthodes alternatives, telles que le passage du jeton par l'environnement ou un drapeau de ligne de commande. Stocker des jetons secrets directement dans un référentiel peut poser un problème de sécurité.

Authentification utilisant le jeton d'accès de la plateforme

Les jetons API de la plateforme ne sont pas acceptés directement par le CLI Strings. Les utilisateurs doivent d'abord les échanger contre un jeton d'accès produit à durée limitée (JWT) puis utiliser le jeton retourné par 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.

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
Téléchargé de vers config/locales/de.yml
Téléchargé en vers 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 continue ensuite à télécharger les paramètres régionaux. Le client affiche Limite de débit dépassée, le téléchargement reprendra dans x secondes.

Commande de nettoyage des téléchargements

La commande de nettoyage des téléchargements est fournie pour supprimer les clés qui se trouvent dans le projet mais qui ne sont pas contenues dans le fichier télé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 un paramètre régional par défaut ou dans un autre paramètre régional :

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Options de format

Plusieurs formats, tels que CSV, prennent en charge des options de format supplémentaires lors du télé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 à travers 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és pour les opérations de pull et de push.

Configuration d'exemple du fichier phrase.yml :

phrase :
  access_token : access_token
  file_format : yml
  push :
    sources :
      -
        file : chemin/vers/votre/fichier.yml
        project_id : project_id
        params :
          locale_id : en
          translation_key_prefix : prefix_
  pull :
    targets :
      -
        file : chemin/vers/votre/fichier.yml
        project_id : project_id
        params :
          translation_key_prefix : prefix_
          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 fichier=@/chemin/vers/mon/fichier.format \
  -F file_format=format \
  -F locale_id=locale_id

curl "https://api.phrase.com/v2/projects/:id_projet/locales/:id/télécharger?file_format=format_fichier&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 :
    - fichier : file.xml
      params :
        options_de_format :
          convertir_espace_réservé : vrai

  push :
    sources :
    - fichier : file.csv
      params :
        options_de_format :
          séparateur_de_colonne : ";"

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 récupération séparée pour chaque paramètre linguistique, utilisez le paramètre global locale_mapping combiné avec l'espace réservé <locale_name>. La CLI utilisera le nom personnalisé du mappage pour le paramètre linguistique correspondant et reviendra au code de langue 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 aux noms de répertoire spécifiques à Android
  locale_mapping :
    en-US : valeurs
    de-DE : valeurs-de-rDE
    fr-FR : valeurs-fr

  push :
    sources :
      # Le fichier source est la langue par défaut, mappé à 'values'
      - fichier : ./app/src/main/res/values/strings.xml
        params :
          locale_id : en-US # Doit correspondre à la locale source dans Phrase

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