CLI

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

Instalação

npm

npm i -D @formatjs/cli

yarn

yarn add -D @formatjs/cli

Adicione o seguinte comando aos scripts do seu package.json:

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

Desenvolvemos esta CLI que ajuda você a extrair mensagens de uma lista de arquivos. Ela utiliza @formatjs/ts-transformer internamente e deve conseguir extrair mensagens se você estiver usando um dos mecanismos abaixo:

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

Extração

npm

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

yarn

yarn 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:

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

cuidado

Sempre coloque seu padrão glob entre aspas (" ou '), como "src/**/*", para evitar a expansão automática do shell, que varia conforme seu terminal (zsh vs fish vs bash).

--format [path]

Caminho para um arquivo de formatador que define a estrutura do arquivo JSON gerado por --out-file. O arquivo de formatador deve exportar uma função chamada format com a assinatura adequada.

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

Isso é especialmente útil para converter nosso formato extraído para um formato específico de TMS.

Veja exemplos em nossos formatadores embutidos.

--in-file [path]

Arquivo contendo a lista de caminhos de arquivos para extração. Útil para contornar limites de linha de comando do bash.

--out-file [path]

Caminho de destino onde o plugin gerará um arquivo .json consolidado com todas as traduções dos files fornecidos. Esta flag ignora --messages-dir.

--id-interpolation-pattern [pattern]

Se descritores de mensagem não possuírem ID, este pattern gerará IDs automaticamente. Padrão: [sha512:contenthash:base64:6]. Veja createHash do nodejs crypto para algoritmos de hash e docs de buffer do nodejs para codificações de digest.

--extract-source-location

Define se metadados de localização da mensagem no arquivo fonte serão extraídos. Se true, campos file, start e end existirão em cada descritor. (padrão: false)

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

Nomes adicionais de componentes para extração, ex: ['FormattedFooBarMessage']. NOTA: Por padrão verificamos se FormattedMessage é importado de moduleSourceName para validar aliases. Esta opção não faz essa verificação, sendo menos segura.

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

Nomes adicionais de funções para extração, ex: ['$t'].

--ignore [files]

Lista de padrões glob de caminhos para não extrair traduções.

--throws

Define se uma exceção será lançada ao falhar no processamento de qualquer arquivo do lote.

--pragma [pragma]

Analisa pragma personalizado adicional específico. Permite marcar arquivos com metadados como project. Exemplo com este arquivo:

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

com a opção {pragma: "intl-meta"}, extraímos // @intl-meta project:my-custom-project para {project: 'my-custom-project'} no arquivo resultante.

--preserve-whitespace

Define se espaços em branco e quebras de linha serão preservados na saída. Normalmente removemos espaços consecutivos e quebras por serem frequentemente usados para estilização.

--flatten

Define se seletores serão elevados e frases niveladas ao máximo. Ex:

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

torna-se

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

O objetivo é fornecer o máximo de frases completas possível, já que frases fragmentadas não são amigáveis para tradução.

Verificação

Verifique arquivos de tradução para garantir que as chaves estão traduzidas e as mensagens são estruturalmente compatíveis com o idioma de origem.

npm

npm run formatjs verify [options] <translationFiles>

yarn

yarn formatjs verify [options] <translationFiles>

--source-locale <sourceLocale>

O idioma de origem dos arquivos de tradução. Deve existir um arquivo chamado <sourceLocale>.json na lista de traduções. Isso serve como referência para verificar outras traduções.

--missing-keys

Verifica se há chaves ausentes no idioma de destino comparado ao idioma de origem. Isso basicamente garante que nenhuma mensagem ficou sem tradução.

--structural-equality

Verifica a igualdade estrutural das mensagens entre o idioma de origem e o destino. Isso assegura que as traduções são formatáveis e não faltam tokens.

--extra-keys

Define se deve verificar a existência de chaves presentes no idioma de destino mas ausentes no idioma de origem. Isso garante que os arquivos de tradução não contenham chaves obsoletas ou não utilizadas.

Compilação

Compila arquivos extraídos do formatjs extract para um formato JSON consumível pelo react-intl. Também realiza verificação de mensagens ICU. Veja Distribuição de Mensagens para detalhes.

npm

npm run compile -- --help

yarn

yarn compile --help

--format [path]

Caminho para um arquivo de formatação que converte <translation_file> em Record<string, string> para compilação. O arquivo deve exportar uma função nomeada compile com a assinatura:

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

É especialmente útil para converter formatos específicos de TMS de volta para o formato react-intl.

Veja exemplos em nossos formatadores embutidos.

--out-file <output>

Arquivo de destino contendo as mensagens compiladas.

--ast

Define se a mensagem será compilada em AST em vez de string. Veja Uso Avançado.

--pseudo-locale <pseudoLocale>

Compila mensagens em pseudo-localidades. Opções disponíveis:

Dada a mensagem em inglês my name is {name}

Locale	Message
xx-LS	my name is {name}SSSSSSSSSSSSSSSSSSSSSSSSS
xx-AC	MY NAME IS {name}
xx-HA	[javascript]my name is {name}
en-XA	[ḿẏ ƞȧȧḿḗḗ īş {name}]
en-XB	‮ɯʎ uɐɯǝ ıs {name}‬

cuidado

Requer --ast

Extração e compilação em um único script

Em alguns ambientes, você pode querer extrair mensagens diretamente para um arquivo pronto para uso com react-intl, sem formato intermediário. Isso é útil para criar rapidamente arquivos no idioma original com mensagens padrão, ou para integração com sistemas TMS que funcionam melhor com arquivos compilados. Note que arquivos compilados não contêm descrições de mensagens, dificultando o trabalho de tradutores. O ideal é usar um formatador personalizado para extrair em formatos compatíveis com seu TMS.

Para extrair e compilar em um único script, configure no package.json como neste exemplo:

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

Detalhamento do script

O script extract-compile executa três operações sequenciais:

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

O primeiro script extrai mensagens de todos os arquivos TypeScript localizados em subpastas de src. Pode ser necessário ignorar certos arquivos que podem disparar erros ou avisos no script, como --ignore myFolder/myFile.ts

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

2. Compila mensagens de temp.json para lang/en.json (arquivo pronto para consumo pelo react-intl)

rm temp.json

3. Remove o arquivo temporário temp.json (opcional - remova este passo se quiser manter o arquivo)

Arquivos resultantes

Aqui você pode ver a diferença entre os formatos extraído (usando o formatador padrão) e o compilado. No script acima, temp.json é o arquivo extraído e en.json é o arquivo compilado.

Extracted messages

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

Compiled messages

{
  "hak27d": "Control Panel",
  "haqsd": "Delete user {name}",
  "19hjs": "New Password",
  "explicit-id": "Confirm Password"
}

Compilação de Pasta

Compile em lote uma pasta com arquivos extraídos do formatjs extract para uma pasta contendo arquivos JSON consumíveis pelo react-intl. Isso também realiza a verificação de mensagens ICU. Veja Distribuição de Mensagens para mais detalhes.

npm

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

yarn

yarn formatjs compile-folder [options] <folder> <outFolder>

A estrutura de pastas deve estar no formato <folder>/<locale>.json e a saída será <outFolder>/<locale>.json.

--format [path]

Caminho para um arquivo de formatação que converte <translation_file> em Record<string, string> para compilação. O arquivo deve exportar uma função nomeada compile com a assinatura:

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

Especialmente útil para converter de formatos específicos de TMS de volta para o formato react-intl.

--ast

Define se a mensagem será compilada em AST em vez de string. Veja Uso Avançado.

--skip-errors

Define se a compilação continua após encontrar erros de análise. Chaves com erros serão omitidas no arquivo de saída.

Formatadores Integrados

Fornecemos os seguintes formatadores integrados para integração com TMS de terceiros:

TMS	--format
BabelEdit	simple
Crowdin Chrome JSON	crowdin
Lingohub	simple
Localize's Simple JSON	simple
Localizely	simple
locize	simple
Lokalise Structured JSON	lokalise
Phrase	simple
POEditor Key-Value JSON	simple
SimpleLocalize	simple
Smartling ICU JSON	smartling
Transifex's Structured JSON	transifex

cuidado

Os format de extract e compile devem ser idênticos. Se usar extract --format smartling, deve-se usar compile --format smartling e vice-versa.

Formatadores Personalizados

Você pode fornecer formatadores personalizados usando nossas 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 = () => {}

Consulte nossos formatadores integrados para exemplos.

API Node.js

Instale @formatjs/cli-lib para uso programático.

npm

npm i -D @formatjs/cli-lib

yarn

yarn add -D @formatjs/cli-lib

Extração

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

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

Compilação

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

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

Formatador Personalizado

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
}