Sintaxe de Mensagens

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 →

Ao traduzir textos, você precisará de uma forma para os tradutores expressarem as sutilezas de ortografia, gramática e conjugação inerentes a cada idioma. Utilizamos a sintaxe de mensagens ICU, também adotada em Java e PHP.

A biblioteca intl-messageformat recebe a mensagem e dados de entrada para criar uma string formatada adequadamente. Este recurso está incluído em todas as integrações que oferecemos.

As seções a seguir descrevem a sintaxe de mensagens ICU e demonstram como utilizar esses recursos nas bibliotecas FormatJS:

Princípios Básicos

A transformação mais simples para uma mensagem é uma string literal.

Hello everyone

Todas as outras transformações são feitas através de substituições chamadas "argumentos". Eles são delimitados por chaves ({ e }) e referenciam um valor nos dados de entrada.

Argumento Simples

Você pode usar um argumento {key} para inserir um valor na mensagem. A chave é buscada nos dados de entrada, e a string é interpolada com seu valor.

ICU Message

Hello {who}

Values as JSON

Result

Argumento Formatado

Valores também podem ser formatados conforme seu tipo. Para isso, use um argumento {key, type, format}.

Os elementos do argumento são:

• key é a localização nos dados de entrada onde se encontram os dados

• type: opcional, define como interpretar o valor (veja abaixo)

• format: opcional, refinamento adicional sobre como exibir esse tipo de dado

ICU Message

I have {numCats, number} cats.

Values as JSON

Result

Tipo number

Este tipo formata números de forma sensível ao locale. Ele interpreta os seguintes valores para o elemento opcional format do argumento:

ICU Message

I have {numCats, number} cats.

Values as JSON

Result

ICU Message

Almost {pctBlack, number, ::percent} of them are black.

Values as JSON

Result

Internamente, utiliza a API Intl.NumberFormat. Valores personalizados para o elemento format podem ser definidos e são passados para o construtor Intl.NumberFormat.

Incluir detalhes de formatação numérica oferece ótimo contexto aos tradutores. Também suportamos Esqueletos Numéricos ICU com a mesma sintaxe:

ICU Message

The price of this bagel is {num, number, ::sign-always compact-short currency/GBP}

Values as JSON

Result

Saiba mais aqui.

Para controle preciso de casas decimais, use os símbolos de Precisão Fracionária # e 0, que especificam quantas casas decimais exibir:

ICU Message

The duration is {num, number, ::.##} seconds

Values as JSON

Result

Note que o símbolo # não exibe zeros à direita, como neste exemplo:

ICU Message

The duration is {num, number, ::.##} seconds

Values as JSON

Result

Para exibir zeros à direita, use o símbolo 0:

ICU Message

The very precise number is {num, number, ::.00}

Values as JSON

Result

Para detalhes, consulte Precisão Fracionária.

Tipo date

Este tipo é utilizado para formatar datas de forma sensível ao locale. Ele interpreta os seguintes valores para o elemento opcional de formatação do argumento:

• short: formata datas da maneira mais concisa possível

• medium: formata datas com representação textual curta do mês

• long: formata datas com representação textual longa do mês

• full: formata datas com o máximo de detalhes

ICU Message

Sale begins {start, date, medium}

Values as JSON

Result

Internamente, ele usa a API Intl.DateTimeFormat. Você pode definir valores personalizados para o elemento de formato, que são passados para o construtor Intl.DateTimeFormat.

Tipo time

Este tipo é usado para formatar horários de forma sensível ao locale. Ele interpreta os seguintes valores para o elemento opcional formato do argumento:

• short é usado para formatar horas com horas e minutos

• medium é usado para formatar horas com horas, minutos e segundos

• long é usado para formatar horas com horas, minutos, segundos e fuso horário

• full é igual a long

ICU Message

Coupon expires at {expire, time, short}

Values as JSON

Result

Internamente, ele usa a API Intl.DateTimeFormat. Você pode definir valores personalizados para o elemento de formato, que são passados para o construtor Intl.DateTimeFormat.

Esqueleto de Data/Hora Suportado

Assim como o tipo number, também suportamos o esqueleto de data/hora do ICU. O ICU oferece uma ampla variedade de padrões para personalizar o formato de data/hora. Entretanto, nem todos estão disponíveis na API Intl do ECMA402. Portanto, suportamos apenas os seguintes padrões:

Symbol	Meaning	Notes
G	Era designator
y	year
M	month in year
L	stand-alone month in year
d	day in month
E	day of week
e	local day of week	e..eee is not supported
c	stand-alone local day of week	c..ccc is not supported
a	AM/PM marker
h	Hour [1-12]
H	Hour [0-23]
K	Hour [0-11]
k	Hour [1-24]
m	Minute
s	Second
z	Time Zone

Formato {select}

O formato {key, select, matches} é usado para escolher uma saída correspondendo um valor a uma das opções. (É semelhante à instrução switch encontrada em algumas linguagens de programação.) A chave é buscada nos dados de entrada. O valor correspondente é comparado com um dos matches e a saída correspondente é retornada. O argumento key deve seguir a Sintaxe de Padrões Unicode. O matches é uma lista separada por espaços de correspondências.

O formato de uma correspondência é match {output}. (Uma correspondência é semelhante ao case de uma instrução switch encontrada em algumas linguagens de programação.) O match é um valor literal. Se for igual ao valor de key, então o output correspondente será usado.

O output é em si uma mensagem, portanto pode ser uma string literal ou conter mais argumentos aninhados.

A correspondência other é especial e é usada se nenhuma outra corresponder. (Isso é semelhante ao caso default de uma instrução switch encontrada em algumas linguagens de programação.)

perigo

other é obrigatório conforme a implementação do icu4j. Um erro será lançado se select for usado sem other.

ICU Message

{gender, select,
  male {He will respond shortly.}
  female {She will respond shortly.}
  other {They will respond shortly.}
}

Values as JSON

Result

Aqui está um exemplo de argumentos aninhados.

ICU Message

{isTaxed, select,
  yes {An additional {tax, number, percent} tax will be collected.}
  other {No taxes apply.}
}

Values as JSON

Result

Formato {plural}

O formato {key, plural, matches} é usado para escolher uma saída baseada nas regras de pluralização do idioma atual. É muito semelhante ao formato {select} acima, exceto que o valor deve ser um número e é mapeado para uma categoria de plural.

A correspondência é um valor literal que equivale a uma dessas categorias plurais. Nem todos os idiomas usam todas as categorias.

• zero: Categoria usada em idiomas com gramática especializada para zero itens (ex: árabe e letão).

• one: Esta categoria é usada para idiomas que têm gramática especializada especificamente para um item (singular). Muitos idiomas, mas não todos, usam esta categoria. (Muitos idiomas asiáticos populares, como chinês e japonês, não usam esta categoria.)

• two: Esta categoria é usada para idiomas que têm gramática especializada especificamente para dois itens (dual). (Exemplos são árabe e galês.)

• few: Esta categoria é usada para idiomas que têm gramática especializada especificamente para um número pequeno (paucal) de itens. Em alguns idiomas, isso é usado para 2-4 itens; em outros, para 3-10 itens; e outros idiomas têm regras ainda mais complexas.

• many: Categoria usada em idiomas com gramática especializada para quantidades maiores (ex: árabe, polonês e russo).

• other: Categoria usada quando o valor não se encaixa em outras categorias. Usada para "plural" em idiomas com dicotomia simples "singular/plural" como o inglês.

• =value: Usado para corresponder um valor específico independente das categorias plurais do locale atual.

informação

Não use =1 no lugar de one. one nem sempre significa 1, mas sim singular, que pode corresponder a mais números além de 1 em certos idiomas. Alguns idiomas consideram todos os números terminados em 1 (como 1, 11, 111) como singular.

perigo

other é obrigatório conforme implementação do icu4j. Lançaremos um erro se plural for usado sem other.

ICU Message

{itemCount, plural,
  one {Cart: {itemCount, number} item}
  other {Cart: {itemCount, number} items}
}

Values as JSON

Result

ICU Message

{itemCount, plural,
  =0 {You have no items.}
  one {You have {itemCount, number} item.}
  other {You have {itemCount, number} items.}
}

Values as JSON

Result

Na output da correspondência, você pode usar o token especial # como placeholder para o valor numérico. Ele será formatado como se fosse {key, number}. Este é o estilo que preferimos usar.

ICU Message

{itemCount, plural,
  =0 {You have no items.}
  one {You have # item.}
  other {You have # items.}
}

Values as JSON

Result

Formato {selectordinal}

O formato {key, selectordinal, matches} é usado para escolher saídas baseadas nas regras de pluralização ordinal (1º, 2º, 3º etc.) do locale atual. É muito similar ao formato {plural} acima, exceto que o valor é mapeado para uma categoria plural ordinal.

A correspondência é um valor literal que equivale a uma dessas categorias plurais. Nem todos os idiomas usam todas as categorias.

• zero: Categoria usada em idiomas com gramática especializada para zero itens (ex: árabe e letão).

• one: Categoria usada em idiomas com gramática especializada para um item. Muitos idiomas usam esta categoria, mas não todos (ex: chinês e japonês não usam).

• two: Categoria usada em idiomas com gramática especializada para dois itens (ex: árabe e galês).

• few: Categoria usada em idiomas com gramática especializada para pequenas quantidades. Em alguns idiomas aplica-se a 2-4 itens, em outros a 3-10 itens, com regras complexas variadas.

• many: Categoria usada em idiomas com gramática especializada para quantidades maiores (ex: árabe, polonês e russo).

• other: Categoria usada quando o valor não se encaixa em outras categorias. Usada para "plural" em idiomas com dicotomia simples "singular/plural" como o inglês.

• =value: Usado para corresponder um valor específico independente das categorias plurais do locale atual.

perigo

other é obrigatório conforme implementação do icu4j. Lançaremos um erro se selectordinal for usado sem other.

Na output da correspondência, o token especial # pode ser usado como placeholder para o valor numérico e será formatado como se fosse {key, number}.

ICU Message

It's my cat's {year, selectordinal,
  one {#st}
  two {#nd}
  few {#rd}
  other {#th}
} birthday!

Values as JSON

Result

Formatação de Texto Rico

Também suportamos formatação de texto rico incorporada em mensagens usando tags. Isso permite que desenvolvedores incluam textos mais longos sem fragmentar sentenças. NOTA: Isso não é tag XML/HTML

ICU Message

Our price is <boldThis>{price, number, ::currency/USD precision-integer}</boldThis>
with <link>{pct, number, ::percent} discount</link>

Values as JSON

Result

Comportamento Personalizado

Espera-se que sistemas usando formatação de texto rico tenham métodos externos para tratar esses placeholders. As tags farão parte da saída gerada e podem ser pós-processadas por suas ferramentas ou usando a configuração defaultRichTextElements.

Aspas / Escapamento

O apóstrofo ASCII ' (U+0027) pode ser usado para escapar caracteres sintáticos na parte textual da mensagem, replicando o comportamento de aspas/escapamento do ICU.

ICU Message

This is not an interpolation: '{word}

Values as JSON

Result

ICU Message

These are not interpolations: '{word1} {word2}'

Values as JSON

Result

ICU Message

'<notATag>

Values as JSON

Result

ICU Message

'<notATag>hello</notATag>'

Values as JSON

Result

Dois apóstrofos ASCII consecutivos representam um apóstrofo ASCII, de forma semelhante a como %% no printf representa um %. No entanto, recomendamos usar o apóstrofo curvo ’ (U+2019) para strings legíveis por humanos e reservar o apóstrofo ASCII ' (U+0027) apenas para a sintaxe de mensagens ICU.

ICU Message

This '{isn''t}' obvious.

Values as JSON

Result