Saltar al contenido principal

CLI

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

Instalación​

npm i -D @formatjs/cli

Agrega el siguiente comando a los scripts de tu package.json:

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

Hemos desarrollado esta CLI que te ayuda a extraer mensajes de una lista de archivos. Utiliza @formatjs/ts-transformer internamente y debería poder extraer mensajes si estás declarando usando uno de los siguientes mecanismos:

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

Extracción​

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
precaución

Siempre debes entrecomillar (" o ') tu patrón glob (como "src/**/*") para evitar la expansión automática del shell, que varía según tu terminal (zsh vs fish vs bash).

--format [path]​

Ruta a un archivo formateador que controla la estructura del archivo JSON generado por --out-file. El archivo formateador debe exportar una función llamada format con la firma correspondiente.

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

Es especialmente útil para convertir desde nuestro formato extraído a un formato específico de TMS.

Consulta nuestros formateadores integrados para ver ejemplos.

--in-file [path]​

Archivo que contiene la lista de rutas de archivos a extraer. Es útil para evitar los límites de línea de comandos de bash.

--out-file [path]​

Ruta del archivo destino donde el plugin generará un archivo .json consolidado con todas las traducciones de los files proporcionados. Este flag ignora --messages-dir.

--id-interpolation-pattern [pattern]​

Si ciertos descriptores de mensaje no tienen ID, este pattern se usará para generar IDs automáticamente. Por defecto es [sha512:contenthash:base64:6]. Consulta nodejs crypto createHash para algoritmos de hash y nodejs buffer docs para codificaciones de digest.

--extract-source-location​

Indica si se debe extraer metadatos sobre la ubicación del mensaje en el archivo fuente. Si es true, existirán los campos file, start y end para cada descriptor de mensaje extraído. (predeterminado: false)

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

Nombres de componentes adicionales para extraer mensajes, ej: ['FormattedFooBarMessage']. NOTA: Por defecto verificamos que FormattedMessage se importe desde moduleSourceName para asegurar que los alias funcionen. Esta opción no hace eso, por lo que es menos segura.

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

Nombres de funciones adicionales para extraer mensajes, ej: ['$t'].

--ignore [files]​

Lista de patrones glob de rutas para no extraer traducciones.

--throws​

Indica si se debe lanzar una excepción cuando falle el procesamiento de cualquier archivo en el lote.

--pragma [pragma]​

Analiza pragmas personalizados adicionales específicos. Esto te permite etiquetar ciertos archivos con metadatos como project. Por ejemplo con este archivo:

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

y con la opción {pragma: "intl-meta"}, analizaremos // @intl-meta project:my-custom-project como {project: 'my-custom-project'} en el archivo resultante.

--preserve-whitespace​

Indica si se debe conservar espacios en blanco y saltos de línea en la salida. Normalmente eliminamos espacios consecutivos y saltos de línea ya que suelen usarse indebidamente con fines de estilo.

--flatten​

Indica si se deben elevar selectores y aplanar oraciones tanto como sea posible. Ej:

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

se convierte en

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

El objetivo es proporcionar tantas oraciones completas como sea posible, ya que las oraciones fragmentadas no son amigables para la traducción.

Verificación​

Verifica archivos de traducción para asegurar que las claves están traducidas y los mensajes son estructuralmente compatibles con la localización origen.

npm run formatjs verify [options] <translationFiles>

--source-locale <sourceLocale>​

La localización origen de los archivos de traducción. Debe existir un archivo llamado <sourceLocale>.json en la lista de archivos de traducción. Se utiliza como referencia para verificar otras traducciones.

--missing-keys​

Indica si se deben verificar claves faltantes en la localización destino comparada con la origen. Esto garantiza básicamente que no haya mensajes sin traducir.

--structural-equality​

Indica si se debe verificar la igualdad estructural de mensajes entre las localizaciones origen y destino. Esto asegura que las traducciones sean formateables y no les falten tokens.

--extra-keys​

Indica si se deben verificar claves que existen en la localización destino pero no en la localización origen. Esto garantiza que los archivos de traducción no contengan claves obsoletas o sin usar.

Compilación​

Compila archivos extraídos de formatjs extract a un archivo JSON consumible por react-intl. Esto también realiza verificación de mensajes ICU. Consulta Distribución de mensajes para más detalles.

npm run compile -- --help

--format [path]​

Ruta a un archivo formateador que convierte <translation_file> a Record<string, string> para permitir la compilación. El archivo debe exportar una función llamada compile con la firma:

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

Esto es especialmente útil para convertir desde un formato específico de TMS de vuelta al formato de react-intl.

Consulta nuestros formateadores integrados para ver ejemplos.

--out-file <output>​

El archivo destino que contiene los mensajes compilados.

--ast​

Determina si se compila el mensaje a AST en lugar de solo a cadena. Consulta Uso Avanzado.

--pseudo-locale <pseudoLocale>​

Indica si debemos compilar mensajes en pseudo-localizaciones. Pseudo-localizaciones disponibles:

Dado el mensaje en inglés 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}‬
precaución

Requiere --ast

Extracción y compilación con un solo script​

En algunos entornos, es posible que desees extraer tus mensajes directamente a un archivo listo para usar con react-intl sin usar un formato intermedio de mensajes extraídos. Esto podría ser útil para crear rápidamente el archivo para el idioma original con mensajes predeterminados. También podría ser útil si usas un Sistema de Gestión de Traducciones (TMS) que trabaje mejor con archivos compilados. Ten en cuenta que el archivo compilado no contiene descripciones de mensajes, lo que dificulta el trabajo para traductores. Idealmente, busca o escribe un formateador personalizado que extraiga mensajes a un formato compatible con tu TMS.

Para lograr extracción y compilación en un solo script, puedes configurarlo en package.json como en este ejemplo:

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

Desglose del script​

El script de ejemplo extract-compile consta de tres operaciones realizadas secuencialmente.

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

El primer script extrae mensajes de todos los archivos TypeScript en subcarpetas de src. Es posible que necesites ignorar ciertos archivos que podrían generar errores o advertencias, como --ignore myFolder/myFile.ts.

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

El segundo script compila los mensajes de temp.json al archivo lang/en.json. Este archivo está listo para ser consumido por react-intl.

rm temp.json

El último script elimina el archivo extraído temp.json. Siéntete libre de eliminar este paso si deseas conservar este archivo.

Los archivos resultantes​

Aquí puedes ver la diferencia entre los formatos de archivo extraído (usando el formateador predeterminado) y el compilado. En el script anterior, temp.json es el archivo extraído y en.json es el archivo compilado.

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

Compilación de Directorios​

Compila por lotes un directorio con archivos extraídos mediante formatjs extract a una carpeta que contenga archivos JSON consumibles por react-intl. También realiza verificación de mensajes ICU. Consulta Distribución de Mensajes para más detalles.

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

La estructura de carpetas debe tener la forma <folder>/<locale>.json y la salida será <outFolder>/<locale>.json.

--format [path]​

Ruta a un archivo formateador que convierte <translation_file> a Record<string, string> para permitir la compilación. El archivo debe exportar una función llamada compile con la firma:

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

Es especialmente útil para convertir desde un formato específico de TMS al formato de react-intl.

--ast​

Determina si se compila el mensaje a AST en lugar de solo a cadena. Consulta Uso Avanzado.

--skip-errors​

Determina si continuar compilando mensajes después de encontrar errores en uno de ellos. Las claves con errores no se incluirán en el archivo de salida.

Formateadores Integrados​

Proporcionamos los siguientes formateadores integrados para integración con TMS de terceros:

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
precaución

Los format de extract y compile deben coincidir: si usas extract --format smartling, debes usar también compile --format smartling y viceversa.

Formateadores Personalizados​

Puedes proporcionar tus propios formateadores usando nuestras 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 = () => {}

Consulta nuestro código de formateadores integrados para ver ejemplos.

API de Node​

Instala @formatjs/cli-lib para usar programáticamente.

npm i -D @formatjs/cli-lib

Extracción​

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

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

Compilación​

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

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

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