Die CLI verwenden (Strings)

Steuern Sie, wie der Client Dateien pusht und abruft, indem Sie die Konfigurationsdatei .phrase.yml bearbeiten.

Beispiel:Konfigurationsdatei.

Verwendung von Ausweichregeln und Anführungszeichen

Beim Vorbeiführen an JSON-Objekten in der Kommandozeile kann die Verwendung von Ausweichregeln und Anführungszeichen je nach verwendeter Shell variieren.

Bei einem Windows-Shell, muss die gesamte JSON Zeichenfolge in doppelte Anführungszeichen „“ gesetzt werden und doppelte Anführungszeichen innerhalb von JSON mit einem Backslash \ müssen vermieden werden. Beispiel:

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

Zugriff auf API-Endpunkte

Mit dem Client kann auf alle API-Endpunkte zugreifen werden. Zum Beispiel, um alle Projekte aufzulisten:

$ phrase projects list --access_token ACCESS_TOKEN

Authentifizierung mit Phrase-Anmeldeinformationen

Gib mit --username einen Benutzernamen an, um das Passwort anzufordern_

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

Wenn für den User oder die Organisation Zwei-Faktor-Authentifizierung aktiviert ist, muss ein gültiger Multi-Faktor Token über das -tfa erstattet werden:

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

Authentifizierung mittels Strings-Token

Verwende --zugriff_token, um dein Zugriffstoken anzugeben:

$ phrase projects list --access_token ACCESS_TOKEN

oder verwende die Umgebungsvariable PHRASE_ACCESS_TOKEN, um dein Token zu speichern:

export PHRASE_ACCESS_TOKEN="ACCESS_TOKEN"

Wenn Zwei-Faktor-Authentifizierung aktiviert ist, muss ein gültiger Multi-Faktor Token mit man --x_phrase_app_otp angegeben werden:

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

Ein Token kann auch im interaktiven Modus mit -tfa bereitgestellt werden:

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

Der Zugriffstoken wird standardmäßig aus der Konfigurationsdatei .phrase.yml gelesen, aber das Verhalten kann durch Verwendung der erwähnten Flags oder Umgebungsvariablen außer Kraft gesetzt werden, und das über das Flag oder die Umgebungsvariable bereitgestellte Token wird stattdessen verwendet. Über Flags bereitgestellte Token überschreiben die über die Umgebungsvariable bereitgestellten Token.

Wenn Sie die .phrase.yml-Datei in einem Code-Repository speichern, wird empfohlen, das Token zuerst zu entfernen und alternative Methoden zu verwenden, wie z. B. die Übergabe des Tokens über die Umgebung oder ein Befehlszeilen-Flag. Das Speichern von geheimen Token direkt in einem Repository kann ein Sicherheitsproblem darstellen.

Authentifizierung mittels Platform-Token

Platform-API-Token werden von der Strings-CLI nicht direkt akzeptiert. Benutzer müssen diese zuerst gegen ein kurzlebiges Produkt-Token (JWT) austauschen und dann das zurückgegebene Token über eine der folgenden Optionen verwenden:

Push & Pull

Verwende die Befehle Push und Pull, um Sprachdateien hochzuladen und herunterzuladen. Anstelle von Kommandozeilenargumenten verlassen sich Push und Pull auf die Konfiguration, die in der Konfigurationsdatei .phrase.yml im Stammordner des Projekts gespeichert ist.

Wenn beim Push-Befehl die Option update_translations auf „true“ gesetzt ist, überschreibt der Push-Befehl die Übersetzungen. Der Pull-Befehl überschreibt immer Übersetzungen in der lokalen Datei.

Um Keys in Phrase Strings automatisch zu löschen, wenn sie aus einer Ausgangssprache-Datei entfernt wurden, fügen Sie den Parameter delete_unmentioned_keys: true zum push-Abschnitt der .phrase.yml-Konfigurationsdatei hinzu. Dieser Parameter muss auf der push-Ebene platziert werden, als gleichrangiges Element zu sources, nicht unter params verschachtelt. Dieser Parameter löscht jeden Key im Phrase-Projekt, der in der synchronisierten Datei nicht vorhanden ist. Verwenden Sie dies nur, wenn die Ausgangssprache-Datei alle Keys für das Projekt enthält.

Beispielkonfiguration für das Hoch- und Herunterladen von Sprachdateien einer typischen Rails-Anwendung:

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"

Verwende den Push-Befehl, um Sprachdateien in das Projekt hochzuladen, das durch project_id identifiziert wird, die der Datei de.yml und en.yml im Ordner config/locales entsprechen. Wenn es neue Keys gibt, werden diese der Lokalisierungsdatei hinzugefügt:

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

Verwende den Pull-Befehl, um Sprachdateien von dem durch project_id identifizierten Projekt in die jeweiligen Dateipfade herunterzuladen. Wenn es neue Keys gibt, werden diese dem Projekt hinzugefügt:

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

Unterstützung für Ratelimits

Der Client unterstützt das Ratenlimit für Downloads in Sprachen. Wenn das Ratenlimit erreicht ist, wartet der Client bis das Ratenlimit abgelaufen ist und lädt anschließend Gebietsschemata herunter. Der Client zeigt das Ratenlimit überschritten an. Der Download wird in x Sekunden fortgesetzt.

Upload-Bereinigung

Mit dem Upload-Bereinigungsbefehl werden Keys gelöscht, die im Projekt gefunden werden, aber nicht in der hochgeladenen Datei enthalten sind. Nach dem Pushen von Sprachdateien kann das Löschen aller Keys, die nicht in einer Standardsprache oder einer anderen Sprache enthalten sind, erforderlich sein:

$ phrase uploads cleanup --id <YOUR_UPLOAD_ID>

Format-Optionen

Verschiedene Formate, wie zum Beispiel CSV, unterstützen zusätzliche Formatoptionen beim hochladen. Greife auf diese Optionen zu, indem du die Optionen --format_options voranstellst:

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

Übersetzungs-Key-Präfix

Ein Übersetzungs-Key-Präfix verhindert Key-Kollisionen in verschiedenen Projekten oder Dateien und verbessert die Nachvollziehbarkeit von Übersetzungs-Keys. Das CLI-Interface unterstützt die Key-Präfix-Handhabung sowohl für pull- als auch für push-Operationen.

Beispielkonfiguration der phrase.yml-Datei:

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

Beispiel für Curl-Befehle:

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=format&translation_key_prefix=prefix_&filter_by_prefix=true\" \\
  -u USERNAME_OR_ACCESS_TOKEN

Proxy

Gib hinter einem Proxy Einstellungen mit der Umgebungsvariablen HTTPS_PROXY an:

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

Mehrere Lokalisierungsdateien für ein Projekt

Verwende für jede Sprache eines Projekts eine Datei. Wenn mit Tools oder Frameworks mehrere Dateien verwendet werden müssen, findest du unter Beibehaltung von Dateistrukturen weitere Informationen, wie das Projekt festgelegt werden kann.

Mehrere Projekte für ein Lokalisierungsprojekt

Verteile Übersetzungen an einem großen Lokalisierungsprojekt über mehrere Projekte. Konfiguriere das CLI für den Job mit mehreren Lokalisierungsdateien für ein Lokalisierungsprojekt.

Format-Optionen

Einige Dateiformate erlauben es, Formatoptionen festzulegen, um die Dateisyntax besser kontrollieren zu können. Format in der Konfigurationsdatei .phrase.yml angeben:

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

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

Konfiguration für Android-Projekte

Android verwendet keine ISO-Sprachcodes als Dateimuster. Gib das erforderliche Muster in .phrase.yml an.

Anstatt ein separates Pull-Zielsprache für jede Sprache zu definieren, verwenden Sie die globale locale_mapping-Einstellung in Kombination mit dem <locale_name>-Platzhalter. Das CLI wird den Individuell-Namen aus dem Mapping für die entsprechende Sprache verwenden und für alle anderen Sprachen auf den Standard-Phrase-Sprache-Code zurückgreifen.

Beispiel:

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

  # Phrase-Sprache auf Android-spezifische Verzeichnisnamen mappen
  locale_mapping:
    en-US: values
    de-DE: values-de-rDE
    fr-FR: values-fr

  push:
    sources:
      # Ausgangssprache-Datei ist die Standardsprache, gemappt auf 'values'
      - file: ./app/src/main/res/values/strings.xml
        params:
          locale_id: en-US # Muss mit der Ausgangssprache-Sprache in Phrase Match sein

  pull:
    targets:
      # verwenden Sie den <locale_name>-Platzhalter, der durch das Mapping ersetzt wird
      - file: ./app/src/main/res/<locale_name>/strings.xml