Aller au contenu principal

CLI

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Installation​

npm i -D @formatjs/cli

Ajoutez la commande suivante dans vos scripts du package.json :

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

Nous avons développé cette CLI qui vous permet d'extraire des messages depuis une liste de fichiers. Elle utilise @formatjs/ts-transformer en arrière-plan et peut extraire les messages si vous utilisez l'une des méthodes ci-dessous :

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',
  })
}

Extraction​

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
Attention

Toujours encadrer votre motif glob (" ou ') comme "src/**/*" pour éviter l'expansion automatique par le shell, qui varie selon l'environnement (zsh vs fish vs bash).

--format [path]​

Chemin vers un fichier de formattage qui contrôle la structure du fichier JSON généré par --out-file. Ce fichier doit exporter une fonction nommée format avec la signature appropriée.

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

Particulièrement utile pour convertir notre format extrait vers un format spécifique à un TMS (système de gestion de traduction).

Voir nos formateurs intégrés pour des exemples.

--in-file [path]​

Fichier contenant la liste des chemins de fichiers à extraire. Utile pour contourner les limites de ligne de commande de bash.

--out-file [path]​

Chemin du fichier cible où le plugin écrira un fichier .json agrégé contenant toutes les traductions des files fournies. Ce drapeau ignore --messages-dir.

--id-interpolation-pattern [pattern]​

Si certains descripteurs de message n'ont pas d'ID, ce pattern générera automatiquement des IDs. Valeur par défaut : [sha512:contenthash:base64:6]. Voir nodejs crypto createHash pour les algorithmes de hachage et nodejs buffer docs pour les encodages de digest.

--extract-source-location​

Détermine si les métadonnées de localisation du message dans le fichier source doivent être extraites. Si true, les champs file, start et end seront présents pour chaque descripteur. (par défaut : false)

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

Noms supplémentaires de composants pour l'extraction de messages, ex : ['FormattedFooBarMessage']. NOTE : Par défaut, nous vérifions que FormattedMessage est importé depuis moduleSourceName pour garantir le fonctionnement des alias. Cette option ignore cette vérification et est donc moins sûre.

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

Noms supplémentaires de fonctions pour l'extraction de messages, ex : ['$t'].

--ignore [files]​

Liste de chemins glob à exclure de l'extraction de traductions.

--throws​

Détermine s'il faut lever une exception en cas d'échec du traitement d'un fichier dans le lot.

--pragma [pragma]​

Analyse une pragma personnalisée supplémentaire spécifique. Permet d'étiqueter des fichiers avec des métadonnées comme project. Exemple avec ce fichier :

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

et avec l'option {pragma: "intl-meta"}, nous convertirons // @intl-meta project:my-custom-project en {project: 'my-custom-project'} dans le fichier résultat.

--preserve-whitespace​

Détermine s'il faut conserver les espaces et sauts de ligne en sortie. Nous les supprimons généralement car ils sont souvent utilisés abusivement pour la mise en forme.

--flatten​

Détermine s'il faut remonter les sélecteurs et aplatir les phrases autant que possible. Ex :

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

devient

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

L'objectif est de fournir autant de phrases complètes que possible, car les fragments de phrases ne sont pas adaptés pour la traduction.

Vérification​

Vérifiez les fichiers de traduction pour vous assurer que les clés sont traduites et que les messages sont structurellement compatibles avec la locale source.

npm run formatjs verify [options] <translationFiles>

--source-locale <sourceLocale>​

La locale source des fichiers de traduction. Un fichier nommé <sourceLocale>.json doit exister dans la liste des fichiers de traduction. Il sert de référence pour vérifier les autres traductions.

--missing-keys​

Active la vérification des clés manquantes dans la locale cible par rapport à la locale source. Cela garantit qu'aucun message n'est non traduit.

--structural-equality​

Active la vérification de l'égalité structurelle des messages entre la locale source et la cible. Cela assure que les traductions sont formatables et ne manquent aucun jeton.

--extra-keys​

Détermine s'il faut vérifier les clés présentes dans la locale cible mais absentes de la locale source. Cela garantit que les fichiers de traduction ne contiennent pas de clés obsolètes ou inutilisées.

Compilation​

Compile les fichiers extraits via formatjs extract en un fichier JSON compatible avec react-intl. Effectue également la vérification des messages ICU. Voir Distribution des messages pour plus de détails.

npm run compile -- --help

--format [path]​

Chemin vers un fichier formateur qui convertit <translation_file> en Record<string, string> pour la compilation. Le fichier doit exporter une fonction nommée compile avec la signature :

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

Particulièrement utile pour reconvertir un format spécifique à un TMS vers le format react-intl.

Voir nos formateurs intégrés pour des exemples.

--out-file <output>​

Fichier cible contenant les messages compilés.

--ast​

Détermine si le message doit être compilé en AST plutôt qu'en simple chaîne. Voir Utilisation avancée.

--pseudo-locale <pseudoLocale>​

Compile les messages en pseudo-locales. Options disponibles :

Pour le message anglais 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}‬
Attention

Nécessite --ast

Extraction et compilation avec un seul script​

Dans certains environnements, vous pouvez vouloir extraire vos messages directement dans un format prêt à l'emploi pour react-intl, sans utiliser de format intermédiaire. Ceci est utile pour créer rapidement le fichier de langue originale utilisant les messages par défaut, ou pour des systèmes de gestion de traduction (TMS) fonctionnant mieux avec les fichiers compilés. Notez que les fichiers compilés ne contiennent pas les descriptions des messages, ce qui les rend moins pratiques pour les traducteurs. L'idéal est d'utiliser un formateur personnalisé adapté à votre TMS.

Pour réaliser extraction et compilation en un seul script, configurez simplement un exemple dans package.json :

"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"
}

Détail du script​

Le script extract-compile exécute trois opérations séquentielles.

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

La première commande extrait les messages de tous les fichiers TypeScript dans les sous-dossiers de src. Excluez les fichiers problématiques avec --ignore myFolder/myFile.ts.

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

La deuxième commande compile les messages de temp.json dans lang/en.json, prêt pour react-intl.

rm temp.json

La dernière commande supprime le fichier d'extraction temp.json. Supprimez cette étape si vous souhaitez conserver le fichier.

Fichiers résultants​

Vous pouvez observer ici la différence entre les formats de fichier extrait (utilisant le formateur par défaut) et compilé. Dans le script ci-dessus, temp.json représente le fichier extrait tandis que en.json est le fichier compilé.

{
  "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"
  }
}

Compilation de dossier​

Compilez par lot un dossier contenant des fichiers extraits via formatjs extract vers un dossier contenant des fichiers JSON compatibles react-intl. Cette opération inclut également la vérification des messages ICU. Voir Distribution des messages pour plus de détails.

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

La structure du dossier doit suivre le format <folder>/<locale>.json et la sortie sera <outFolder>/<locale>.json.

--format [path]​

Chemin vers un fichier formateur qui convertit <translation_file> en Record<string, string> pour la compilation. Le fichier doit exporter une fonction nommée compile avec la signature :

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

Particulièrement utile pour reconvertir un format spécifique à un TMS vers le format react-intl.

--ast​

Détermine si le message doit être compilé en AST plutôt qu'en simple chaîne. Voir Utilisation avancée.

--skip-errors​

Détermine si la compilation doit continuer après une erreur de traitement. Les clés comportant des erreurs seront exclues du fichier de sortie.

Formateurs intégrés​

Nous fournissons les formateurs intégrés suivants pour l'intégration avec des TMS tiers :

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
Attention

Les format d'extract et compile doivent être identiques : si vous utilisez extract --format smartling, vous devez également utiliser compile --format smartling et vice versa.

Formateurs personnalisés​

Vous pouvez implémenter votre propre formateur en utilisant nos interfaces :

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 = () => {}

Consultez notre code de formateur intégré pour des exemples.

API Node​

Installez @formatjs/cli-lib pour une utilisation programmatique.

npm i -D @formatjs/cli-lib

Extraction​

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

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

Compilation​

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

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

Formateur personnalisé​

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
}