Zum Hauptinhalt springen

CLI

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Installation​

npm i -D @formatjs/cli

Fügen Sie den folgenden Befehl zu Ihren package.json-scripts hinzu:

{
  "scripts": {
    "extract": "formatjs extract",
    "compile": "formatjs compile"
  }
}

Wir haben dieses CLI entwickelt, das Ihnen hilft, Nachrichten aus Dateien zu extrahieren. Es nutzt intern @formatjs/ts-transformer und kann Nachrichten extrahieren, wenn Sie eine der folgenden Methoden verwenden:

import {defineMessages, defineMessage} from 'react-intl'

defineMessages({
  foo: {
    id: 'foo',
    defaultMessage: 'foo',
    description: 'bar',
  },
})

defineMessage({
  id: 'single',
  defaultMessage: 'single message',
  description: 'header',
})
import {FormattedMessage} from 'react-intl'
;<FormattedMessage id="foo" defaultMessage="foo" description="bar" />
function Comp(props) {
  const {intl} = props
  return intl.formatMessage({
    // The whole `intl.formatMessage` is required so we can extract
    id: 'foo',
    defaultMessage: 'foo',
    description: 'bar',
  })
}

Extraktion​

npm run extract -- --help
# Usage: formatjs extract [options] [files...]

# Extract string messages from React components that use react-intl.
# The input language is expected to be TypeScript or ES2017 with JSX.

For example:

npm run extract -- "src/**/*.{ts,tsx,vue}" --out-file lang.json
Vorsicht

Sie sollten Ihr Glob-Muster immer in Anführungszeichen (" oder ') setzen (z.B. "src/**/*"), um die automatische Shell-Erweiterung zu vermeiden, die je nach Shell (zsh vs fish vs bash) variiert.

--format [path]​

Pfad zu einer Formatierungsdatei, die die Struktur der JSON-Datei von --out-file steuert. Die Formatierungsdatei muss eine Funktion namens format mit der entsprechenden Signatur exportieren.

type FormatFn = <T = Record<string, MessageDescriptor>>(
  msgs: Record<string, MessageDescriptor>
) => T

Dies ist besonders nützlich, um unser extrahiertes Format in ein TMS-spezifisches Format zu konvertieren.

Beispiele finden Sie in unseren integrierten Formatierern.

--in-file [path]​

Die Datei, die eine Liste der zu extrahierenden Dateipfade enthält. Nützlich zur Umgehung von Bash-Befehlszeilenlimits.

--out-file [path]​

Ziel-Dateipfad, in dem das Plugin eine aggregierte .json-Datei aller Übersetzungen aus den angegebenen files ausgibt. Diese Option ignoriert --messages-dir.

--id-interpolation-pattern [pattern]​

Falls Nachrichtendeskriptoren keine ID haben, wird dieses pattern zur automatischen Generierung verwendet. Standard: [sha512:contenthash:base64:6]. Siehe nodejs crypto createHash für Hash-Algorithmen und nodejs buffer docs für Digest-Kodierungen.

--extract-source-location​

Legt fest, ob Metadaten zur Nachrichtenposition in der Quelldatei extrahiert werden. Bei true existieren file, start und end Felder für jeden Deskriptor. (Standard: false)

--additional-component-names [comma-separated-names]​

Zusätzliche Komponentennamen zur Nachrichtenextraktion, z.B. ['FormattedFooBarMessage']. HINWEIS: Standardmäßig wird geprüft, ob FormattedMessage aus moduleSourceName importiert wird, um Variablenaliase sicherzustellen. Diese Option führt diese Prüfung nicht durch und ist weniger sicher.

--additional-function-names [comma-separated-names]​

Zusätzliche Funktionsnamen zur Nachrichtenextraktion, z.B. ['$t'].

--ignore [files]​

Liste von Glob-Pfaden, aus denen keine Übersetzungen extrahiert werden sollen.

--throws​

Legt fest, ob bei Verarbeitungsfehlern einer Datei im Batch eine Exception geworfen wird.

--pragma [pragma]​

Parst spezifische benutzerdefinierte Pragmas. Ermöglicht das Tagging von Dateien mit Metadaten wie project. Beispiel:

// @intl-meta project:my-custom-project
import {FormattedMessage} from 'react-intl'
;<FormattedMessage defaultMessage="foo" id="bar" />

Mit Option {pragma: "intl-meta"} wird // @intl-meta project:my-custom-project in {project: 'my-custom-project'} in der Ergebnisdatei geparst.

--preserve-whitespace​

Legt fest, ob Leerzeichen und Zeilenumbrüche in der Ausgabe erhalten bleiben. Wir entfernen normalerweise aufeinanderfolgende Leerzeichen/Zeilenumbrüche, da diese oft für Stilisierungen missbraucht werden.

--flatten​

Legt fest, ob Selektoren angehoben und Sätze maximal vereinfacht werden sollen. Beispiel:

I have {count, plural, one{a dog} other{many dogs}}

wird zu

{count, plural, one{I have a dog} other{I have many dogs}}

Das Ziel ist es, möglichst viele vollständige Sätze bereitzustellen, da fragmentierte Sätze für Übersetzer nicht optimal geeignet sind.

Überprüfung​

Überprüfen Sie Übersetzungsdateien, um sicherzustellen, dass Schlüssel übersetzt wurden und Nachrichten strukturell mit der Quell-Locale kompatibel sind.

npm run formatjs verify [options] <translationFiles>

--source-locale <sourceLocale>​

Die Quell-Locale der Übersetzungsdateien. Es muss eine Datei namens <sourceLocale>.json in der Liste der Übersetzungsdateien vorhanden sein. Diese dient als Quelle für die Überprüfung anderer Übersetzungen.

--missing-keys​

Legt fest, ob fehlende Schlüssel in der Ziel-Locale im Vergleich zur Quell-Locale überprüft werden sollen. Stellt sicher, dass keine Nachrichten unübersetzt bleiben.

--structural-equality​

Legt fest, ob die strukturelle Gleichheit von Nachrichten zwischen Quell- und Ziel-Locale überprüft werden soll. Stellt sicher, dass Übersetzungen formattierbar sind und keine Tokens fehlen.

--extra-keys​

Legt fest, ob Schlüssel überprüft werden sollen, die in der Ziel-Locale vorhanden sind, aber nicht in der Quell-Locale. Stellt sicher, dass Übersetzungsdateien keine veralteten oder ungenutzten Schlüssel enthalten.

Kompilierung​

Kompiliert extrahierte Dateien von formatjs extract in eine react-intl-kompatible JSON-Datei. Führt auch ICU-Nachrichtenüberprüfung durch. Weitere Details unter Nachrichtenverteilung.

npm run compile -- --help

--format [path]​

Pfad zu einer Formatter-Datei, die <translation_file> in Record<string, string> konvertiert. Die Datei muss eine Funktion namens compile exportieren mit folgender Signatur:

type CompileFn = <T = Record<string, MessageDescriptor>>(
  msgs: T
) => Record<string, string>

Besonders nützlich, um von einem TMS-spezifischen Format zurück in das react-intl-Format zu konvertieren.

Beispiele finden Sie in unseren integrierten Formatierern.

--out-file <output>​

Die Zieldatei, die kompilierte Nachrichten enthält.

--ast​

Legt fest, ob Nachrichten als AST statt als String kompiliert werden. Siehe Erweiterte Nutzung

--pseudo-locale <pseudoLocale>​

Legt fest, ob Nachrichten stattdessen in Pseudo-Locales kompiliert werden sollen. Verfügbare Pseudo-Locales:

Gegeben die englische Nachricht my name is {name}

LocaleMessage
xx-LSmy name is {name}SSSSSSSSSSSSSSSSSSSSSSSSS
xx-ACMY NAME IS {name}
xx-HA[javascript]my name is {name}
en-XA[ḿẏ ƞȧȧḿḗḗ īş {name}]
en-XB‮ɯʎ uɐɯǝ ıs {name}‬
Vorsicht

Erfordert --ast

Extraktion und Kompilierung mit einem Skript​

In einigen Umgebungen möchten Sie Nachrichten direkt in ein für react-intl verwendbares Format extrahieren, ohne Zwischenformat. Nützlich für schnelle Erstellung von Dateien mit Standardnachrichten oder bei TMS-Nutzung. Beachten Sie: Kompilierte Dateien enthalten keine Nachrichtenbeschreibungen, was Übersetzern die Arbeit erschwert. Idealerweise verwenden Sie einen benutzerdefinierten Formatierer für Ihr TMS.

Richten Sie hierfür ein Skript in package.json ein, z.B.:

"scripts": {
  "extract": "formatjs extract",
  "compile": "formatjs compile",
  "extract-compile": "formatjs extract 'src/**/*.ts*' --out-file temp.json --flatten --id-interpolation-pattern '[sha512:contenthash:base64:6]' && formatjs compile 'temp.json' --out-file lang/en.json && rm temp.json"
}

Skriptaufschlüsselung​

Das extract-compile-Beispielskript führt drei Operationen nacheinander aus.

formatjs extract 'src/**/*.ts*' --out-file temp.json --flatten --id-interpolation-pattern '[sha512:contenthash:base64:6]'

Das erste Skript extrahiert Nachrichten aus allen TypeScript-Dateien in src-Unterordnern. Ignorieren Sie ggf. Dateien mit --ignore myFolder/myFile.ts, die Fehler verursachen könnten.

formatjs compile 'temp.json' --out-file lang/en.json

Das zweite Skript kompiliert Nachrichten aus temp.json in lang/en.json – direkt verwendbar mit react-intl.

rm temp.json

Das letzte Skript löscht temp.json. Entfernen Sie diesen Schritt, wenn Sie die Datei behalten möchten.

Ergebnisdateien​

Hier sehen Sie den Unterschied zwischen den extrahierten (mit Standardformatter) und kompilierten Dateiformaten. Im obigen Skript ist temp.json die extrahierte Datei und en.json die kompilierte Datei.

{
  "hak27d": {
    "defaultMessage": "Control Panel",
    "description": "title of control panel section"
  },
  "haqsd": {
    "defaultMessage": "Delete user {name}",
    "description": "delete button"
  },
  "19hjs": {
    "defaultMessage": "New Password",
    "description": "placeholder text"
  },
  "explicit-id": {
    "defaultMessage": "Confirm Password",
    "description": "placeholder text"
  }
}

Ordnerkompilierung​

Kompiliert einen Ordner mit extrahierten Dateien von formatjs extract zu einem Ordner mit für react-intl nutzbaren JSON-Dateien. Führt auch ICU-Nachrichtenvalidierung durch. Weitere Details unter Nachrichtenverteilung.

npm run formatjs compile-folder [options] <folder> <outFolder>

Die Ordnerstruktur muss im Format <folder>/<locale>.json vorliegen, die Ausgabe erfolgt als <outFolder>/<locale>.json.

--format [path]​

Pfad zu einer Formatter-Datei, die <translation_file> in Record<string, string> konvertiert. Die Datei muss eine Funktion namens compile exportieren mit folgender Signatur:

type CompileFn = <T = Record<string, MessageDescriptor>>(
  msgs: T
) => Record<string, string>

Besonders nützlich zur Konvertierung von TMS-spezifischen Formaten zurück in react-intl-Format.

--ast​

Legt fest, ob Nachrichten als AST statt als String kompiliert werden. Siehe Erweiterte Nutzung

--skip-errors​

Bestimmt, ob die Kompilierung nach einem Verarbeitungsfehler fortgesetzt wird. Schlüssel mit Fehlern werden nicht in die Ausgabedatei aufgenommen.

Integrierte Formatter​

Folgende integrierte Formatter stehen für die Integration mit Drittanbieter-TMS zur Verfügung:

TMS--format
BabelEditsimple
Crowdin Chrome JSONcrowdin
Lingohubsimple
Localize's Simple JSONsimple
Localizelysimple
locizesimple
Lokalise Structured JSONlokalise
Phrasesimple
POEditor Key-Value JSONsimple
SimpleLocalizesimple
Smartling ICU JSONsmartling
Transifex's Structured JSONtransifex
Vorsicht

Die format-Einstellungen von extract & compile müssen identisch sein. Wenn Sie extract --format smartling nutzen, muss auch compile --format smartling verwendet werden (und umgekehrt).

Benutzerdefinierte Formatter​

Eigene Formatter können über unsere Schnittstellen bereitgestellt werden:

import {FormatFn, CompileFn, Comparator} from '@formatjs/cli'

interface VendorJson {}

// [Optional] Format @formatjs/cli structure to vendor's structure
export const format: FormatFn<VendorJson> = () => {}
// [Optional] Format vendor's structure to @formatjs/cli structure
export const compile: CompileFn<VendorJson> = () => {}
// [Optional] Sort the messages in a specific order during serialization
export const compareMessages: Comparator = () => {}

Beispiele finden Sie in unserem Quellcode für integrierte Formatter.

Node-API​

Installieren Sie stattdessen @formatjs/cli-lib für die programmatische Nutzung.

npm i -D @formatjs/cli-lib

Extraktion​

import {extract} from '@formatjs/cli-lib'

const resultAsString: Promise<string> = extract(files, {
  idInterpolationPattern: '[sha512:contenthash:base64:6]',
})

Kompilierung​

import {compile} from '@formatjs/cli-lib'

const resultAsString: Promise<string> = compile(files, {
  ast: true,
})

Benutzerdefinierter Formatter​

import {FormatFn, CompileFn, Comparator} from '@formatjs/cli-lib'

export const format: FormatFn = msgs => msgs

// Sort key reverse alphabetically
export const compareMessages = (el1, el2) => {
  return el1.key < el2.key ? 1 : -1
}

export const compile: CompileFn = msgs => {
  const results: Record<string, string> = {}
  for (const k in msgs) {
    results[k] = msgs[k].defaultMessage!
  }
  return results
}