Vai al contenuto principale

CLI

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

Installazione​

npm i -D @formatjs/cli

Aggiungi il seguente comando agli scripts del tuo package.json:

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

Abbiamo sviluppato questa CLI che ti aiuta a estrarre messaggi da una lista di file. Utilizza @formatjs/ts-transformer internamente e può estrarre messaggi se dichiarati tramite uno dei seguenti meccanismi:

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

Estrazione​

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
attenzione

Racchiudi sempre tra virgolette (" o ') il tuo pattern glob (come "src/**/*") per evitare l'espansione automatica della shell, che varia in base al terminale utilizzato (zsh vs fish vs bash).

--format [path]​

Percorso a un file formattatore che definisce la struttura del file JSON generato da --out-file. Il file formattatore deve esportare una funzione chiamata format con la firma appropriata.

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

Particolarmente utile per convertire dal nostro formato estratto a un formato specifico per TMS.

Vedi i nostri formatter integrati per esempi.

--in-file [path]​

File contenente l'elenco dei percorsi dei file da estrarre. Utile per superare il limite della riga di comando di bash.

--out-file [path]​

Percorso del file di destinazione dove il plugin scriverà un file .json aggregato contenente tutte le traduzioni dai files forniti. Questo flag ignorerà --messages-dir.

--id-interpolation-pattern [pattern]​

Se alcuni descrittori di messaggio non hanno ID, questo pattern genererà automaticamente gli ID. Predefinito: [sha512:contenthash:base64:6]. Consulta crypto createHash di Node.js per gli algoritmi di hash e documentazione buffer di Node.js per le codifiche di digest.

--extract-source-location​

Indica se estrarre i metadati sulla posizione del messaggio nel file sorgente. Se true, ogni descrittore estratto avrà i campi file, start e end. (predefinito: false)

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

Nomi aggiuntivi di componenti da cui estrarre messaggi, es: ['FormattedFooBarMessage']. NOTA: Di default verifichiamo che FormattedMessage sia importato da moduleSourceName per garantire il funzionamento degli alias. Questa opzione non effettua tale verifica ed è quindi meno sicura.

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

Nomi aggiuntivi di funzioni da cui estrarre messaggi, es: ['$t'].

--ignore [files]​

Elenco di percorsi glob da cui non estrarre traduzioni.

--throws​

Indica se generare un'eccezione in caso di errore durante l'elaborazione di qualsiasi file nel batch.

--pragma [pragma]​

Analizza un pragma personalizzato aggiuntivo specifico. Permette di taggare file con metadati come project. Ad esempio con questo file:

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

e con l'opzione {pragma: "intl-meta"}, analizzeremo // @intl-meta project:my-custom-project convertendolo in {project: 'my-custom-project'} nel file risultato.

--preserve-whitespace​

Indica se preservare spazi bianchi e a capo nell'output. Rimuoviamo normalmente spazi consecutivi e a capo poiché spesso abusati per scopi di styling.

--flatten​

Indica se elevare i selettori e appiattire le frasi il più possibile. Es:

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

diventa

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

L'obiettivo è fornire il maggior numero possibile di frasi complete poiché le frasi frammentate non sono di facile traduzione.

Verifica​

Verifica i file di traduzione per assicurarsi che le chiavi siano tradotte e che i messaggi siano strutturalmente compatibili con la lingua di origine.

npm run formatjs verify [options] <translationFiles>

--source-locale <sourceLocale>​

La lingua di origine dei file di traduzione. Deve esistere un file denominato <sourceLocale>.json nell'elenco dei file di traduzione. Questo viene utilizzato come sorgente per verificare le altre traduzioni.

--missing-keys​

Indica se verificare la presenza di chiavi mancanti nella lingua di destinazione rispetto a quella di origine. Ciò garantisce sostanzialmente che non ci siano messaggi non tradotti.

--structural-equality​

Indica se verificare l'uguaglianza strutturale dei messaggi tra la lingua di origine e quella di destinazione. Ciò assicura che le traduzioni siano formattabili e non manchino di alcun token.

--extra-keys​

Indica se verificare la presenza di chiavi esistenti nella lingua di destinazione ma non in quella di origine. Ciò garantisce che i file di traduzione non contengano chiavi obsolete o inutilizzate.

Compilazione​

Compila i file estratti da formatjs extract in un file JSON utilizzabile da react-intl. Questa operazione esegue anche la verifica dei messaggi ICU. Vedere Distribuzione dei messaggi per maggiori dettagli.

npm run compile -- --help

--format [path]​

Percorso a un file formattatore che converte <translation_file> in Record<string, string> per la compilazione. Il file deve esportare una funzione chiamata compile con la firma:

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

È particolarmente utile per convertire da un formato specifico di un TMS al formato react-intl.

Vedi i nostri formatter integrati per esempi.

--out-file <output>​

Il file di destinazione che contiene i messaggi compilati.

--ast​

Se compilare i messaggi in AST invece che in semplice stringa. Vedi Utilizzo Avanzato

--pseudo-locale <pseudoLocale>​

Indica se compilare i messaggi in pseudo-lingue. Pseudo-lingue disponibili:

Dato il messaggio in inglese 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}‬
attenzione

Richiede --ast

Estrazione e compilazione con un singolo script​

In alcuni ambienti potresti voler estrarre i messaggi in un file pronto per l'uso con react-intl senza utilizzare un formato di file intermedio per i messaggi estratti. Ciò potrebbe essere utile per creare rapidamente e facilmente il file per la lingua originale che utilizza i messaggi predefiniti. Potrebbe anche essere utile se si utilizza un sistema di gestione delle traduzioni (TMS) particolarmente adatto a lavorare con i file compilati. Tieni presente che il file compilato non contiene le descrizioni dei messaggi, quindi è più difficile da utilizzare per i traduttori. Idealmente, dovresti trovare o scrivere un formatter personalizzato che puoi utilizzare per estrarre i messaggi in un formato di file compatibile con il tuo TMS.

Per eseguire estrazione e compilazione in un singolo script, puoi semplicemente impostare uno script nel package.json come in questo esempio:

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

Analisi dello script​

Lo script di esempio extract-compile consiste in tre operazioni eseguite una dopo l'altra.

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

Il primo script estrae i messaggi da tutti i file TypeScript che si trovano nelle sottocartelle di src. Potresti dover ignorare alcuni file che potrebbero causare errori o avvisi nello script, ad esempio --ignore myFolder/myFile.ts.

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

Il secondo script compila i messaggi da temp.json nel file lang/en.json. Questo file è pronto per essere utilizzato da react-intl.

rm temp.json

L'ultimo script elimina il file estratto temp.json. Sentiti libero di rimuoverlo dallo script se desideri conservare questo file.

I file risultanti​

Qui puoi vedere la differenza tra i formati dei file estratti (utilizzando il formattatore predefinito) e quelli compilati. Nello script precedente, temp.json è il file estratto e en.json è il file compilato.

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

Compilazione della Cartella​

Compila in batch una cartella con file estratti da formatjs extract in una cartella contenente file JSON utilizzabili da react-intl. Esegue anche la verifica dei messaggi ICU. Vedi Distribuzione dei Messaggi per maggiori dettagli.

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

La struttura della cartella dovrebbe essere nella forma <folder>/<locale>.json e l'output sarà <outFolder>/<locale>.json.

--format [path]​

Percorso a un file formattatore che converte <translation_file> in Record<string, string> per la compilazione. Il file deve esportare una funzione chiamata compile con la firma:

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

Particolarmente utile per convertire da un formato specifico di un TMS nuovamente nel formato react-intl.

--ast​

Se compilare i messaggi in AST invece che in semplice stringa. Vedi Utilizzo Avanzato

--skip-errors​

Se continuare la compilazione dopo aver incontrato un errore nell'analisi di un messaggio. Le chiavi con errori non verranno incluse nel file di output.

Formattatori Integrati​

Forniamo i seguenti formattatori integrati per l'integrazione con TMS di terze parti:

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
attenzione

I format di extract e compile devono coincidere: se usi extract --format smartling, devi usare anche compile --format smartling e viceversa.

Formattatori Personalizzati​

Puoi fornire il tuo formattatore utilizzando le nostre interfacce:

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

Consulta il nostro codice dei formattatori integrati per alcuni esempi.

API Node​

Installa @formatjs/cli-lib per l'utilizzo programmatico

npm i -D @formatjs/cli-lib

Estrazione​

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

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

Compilazione​

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

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

Formattatore Personalizzato​

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
}