Localização de texto

O texto na Unreal Engine (UE) é o principal componente para localização. É uma string especializada, representada pelo tipo "FText" em C++. Deve ser usada quando você tiver um texto voltado para o usuário e que precisa ser localizado.

Internamente, o "FText" é implementado como um "TSharedRef" para um "ITextData". Isso facilita muito o processo de cópia, e o utilitário "FTextSnapshot" fornece uma maneira eficiente de detectar se um valor de "FText" em cache foi alterado.

Os dados contidos nas instâncias de "FText" variam dependendo de como o "FText" foi criado. Essa variação é processada pelo "histórico de texto" interno ("FTextHistory"). Os históricos de texto permitem a reconstrução de texto com correção de cultura e também são o componente principal para fazer o seguinte:

• Trocar de cultura em tempo real.

• Enviar "FText" pela rede.

• Criar fontes invariáveis de cultura.

Literais de texto

O texto localizável é formado por três componentes: um Namespace, um Key (que forma a identidade) e um Source String (que é a base do que é traduzido e atua como validação em traduções "obsoletas"). A maneira mais comum de criar um texto localizável na UE é usando um literal de texto.

Como criar literais de texto em C++

É possível criar literais de texto em C++ usando a família de macros "LOCTEXT".

Macros de texto literal

Exemplo:

	// Define o namespace a ser usado com LOCTEXT
	// Isso só é válido em um único arquivo e deve tornar-se indefinido antes do fim do arquivo
	#define LOCTEXT_NAMESPACE "MyNamespace"
	// Crie literais de texto
	constFTextHelloWorld= NSLOCTEXT("MyOtherNamespace","HelloWorld","Olá, mundo!")
	constFTextGoodbyeWorld= LOCTEXT("GoodbyeWorld","Adeus, mundo!")
	// Torne indefinido o namespace antes do fim do arquivo
	#undef LOCTEXT_NAMESPACE
Copy full snippet

Como criar literais de texto em arquivos .ini

É possível criar literais de texto em arquivos .ini usando a sintaxe de macro "NSLOCTEXT" (https://api.unrealengine.com/INT/API/Runtime/Engine/NSLOCTEXT/129/index.html)

Como criar literais de texto em ativos

É possível criar literais de texto usando propriedades de "FText". Uma key é gerada automaticamente, mas você pode definir um namespace ou key personalizada para o texto usando o combo avançado ao lado do campo de texto. Também não há problema em usar o namespace ou a key padrão.

Formatação de texto

A formatação de texto fornece uma forma de combinar texto de uma maneira mais fácil de localizar, usando um padrão de formato localizável que injeta texto real para substituir espaços reservados de formato.

Os placeholders de formato estão contidos em um par de chaves e podem ser números (para formatação baseada em índice) ou strings (para formatação baseada em nome). Por exemplo:

"Você tem {0} de vida restantes." "Você tem {CurrentHealth} pontos de vida restantes."

Os placeholders de formato também podem especificar uma função (chamada de "modificador de argumento") a ser executada nos dados de argumento. Elas são especificadas como um canal seguido pelo nome da função e argumentos. Por exemplo:

"{NumCats} {NumCats}|plural(one=cat,other=cats)"

	Result `{ {Res} }
Copy full snippet

	Result { 10 }
Copy full snippet

	Result \`\`{Res}\`\`  
Copy full snippet

	Result \`10\`
Copy full snippet

Formatação de texto em C++

A formatação de texto em C++ é feita pela família de funções ["FText::Format"] (https://api.unrealengine.com/INT/API/Runtime/Core/Internationalization/FText/Format/1/index.html) Cada função usa um padrão "FTextFormat", que será construído implicitamente a partir de uma instância de "FText", seguido por argumentos adicionais, conforme definido na tabela a seguir.

Formatação de texto em Blueprints

A formatação de texto em Blueprints é feita pelo nó Format Text. Esse nó pode receber um padrão de formato literal, ou ter o padrão vinculado a outro pin de texto.

• Quando um padrão de formato literal for especificado, os pins de argumento de formato serão gerados automaticamente.

• Quando o padrão de formato está vinculado a outro pin de texto, você deve especificar manualmente os argumentos para o formato usando o painel Details do nó.

Modificadores de argumento

Os modificadores de argumento fornecem uma maneira de pré-processar um argumento antes que ele seja adicionado à string formatada. Os modificadores de argumento são extensíveis. Você cria um modificador de argumento implementando a interface "ITextFormatArgumentModifier" e registrando uma função de fábrica para uma determinada palavra-chave (confira "FTextFormatter::RegisterTextArgumentModifier").

A UE fornece alguns modificadores de argumento por padrão: há modificadores para pluralidade, gênero e pós-posições Hangul.

Formas de plurais

As formas de plurais permitem usar textos diferentes com base em uma variável numérica específica do formato de texto. As formas de plurais podem ser cardinais (como "Há 1 gato" ou "Há 4 gatos") ou ordinais (como "Você terminou em primeiro lugar!" ou "Você terminou em segundo!"). Formas de plurais são especificadas como pares de valor-chave e são compatíveis com qualquer uma das seguintes palavras-chave (conforme definido para sua cultura pelos dados de CLDR): zero, um, dois, poucos, muitos, outro. Valores são uma string opcional com aspas que também pode conter marcadores de formato.

Exemplo de formato cardinal:

	"{NumCats}|plural(one=Existe,other=Existem) {NumCats} {NumCats}|plural(one=gato,other=gatos)"

Copy full snippet

Exemplo de formato ordinal:

	"Você ficou em {Place}{Place}|ordinal(one=º,two=º,few=º,other=º)!"

Copy full snippet

Formas de gênero

As formas de gênero permitem usar textos diferentes baseados em um valor "ETextGender" dado ao seu formato de texto, como "Le guerrier est fort" ou "La guerriére est forte". Formas de gênero são especificadas como uma lista de valores da ordem de [masculino, feminino, neutro], em que neutro é opcional. Valores são uma string opcional que também pode conter marcadores de formato.

Exemplo de formato:

	"{Gender}|gender(Le,La) {Gender}|gender(guerrier,guerrière) est {Gender}|gender(fort,forte)"

Copy full snippet

Pós-posições de Hangul

As pós-posições do Hangul ajudam a seguir as regras gramaticais presentes em coreano e inserem os glifos corretos com base no fato de o valor inserido terminar em uma consoante ou uma vogal, como "사람은" ou "사자는". As pós-posições do Hangul são especificadas como uma lista de valores na ordem de [consoante, vogal]. Os valores são uma string entre aspas opcional.

Exemplo de formato:

	"{Arg}|hpp(은,는)"

Copy full snippet

Práticas recomendadas para formatação de texto

• Ao injetar um número que afeta a frase, lide com essas variações usando os modificadores de argumento das formas plurais em vez de ramificar no código. Quando você usa formas plurais, a frase é traduzida corretamente para idiomas que não compartilham as regras de plurais do idioma de origem.

• Ao injetar um nome pessoal, certifique-se de incluir um argumento para o gênero da pessoa. Isso é importante em idiomas com regras gramaticais de gênero, pois permite que os tradutores mudem a tradução com base no gênero (consulte Formas de gênero).

• Evite injetar nomes para objetos (como "mesa", "porta" ou "cadeira") ou esteja preparado para torná-los localizáveis. Esses nomes podem ter um gênero em um idioma e um gênero diferente em outro. Isso impossibilita a localização precisa da string de padrão de formato sem metadados por cultura. O ideal é incluir frases completas em vez de apenas o nome. Isso garantirá traduções precisas.

  Versões futuras da UE podem incluir uma função para que tradutores usem metadados para marcar textos que representam nomes, que eles possam ramificar posteriormente em padrões de formato para produzir traduções precisas.

• Evite concatenar frases parciais. Isso pode causar problemas, pois é possível que cada cláusula ou parte seja traduzida corretamente e a tradução do todo esteja incorreta. É melhor reescrever o texto em frases completas, para garantir uma tradução correta.

Geração de texto

A geração de texto usa dados de internacionalização para produzir texto com correção de cultura que não depende da localização direta. Há três tipos de geração de texto: numérica, cronológica e transformativa.

Geração de texto numérica

A geração numérica é usada para converter tipos numéricos em uma representação de texto legível para humanos. As regras exatas para isso são específicas da cultura e também podem ser ajustadas a cada geração se um controle mais específico for necessário.

Por exemplo, nas regras de geração padrão, o número float "1234.5" seria gerado como "1.234,5". em inglês, "1 234,5" em francês e "١٬٢٣٤٫٥" em árabe.

Geração numérica em C++

A geração numérica em C++ é processada pelas funções a seguir.

A maioria das funções na tabela usa uma "FNumberFormattingOptions" opcional para controlar a saída (o padrão é obtido na localidade ativa) e uma cultura opcional (o padrão é a localidade ativa).

Geração numérica em Blueprints

A geração numérica em Blueprints é processada pelos nós a seguir.

A maioria dos nós na tabela usa argumentos avançados para controlar a saída.

Cronológica

A geração cronológica é usada para converter tipos de data e hora em uma representação de texto legível para humanos. As regras exatas para isso são específicas da cultura, e o estilo de data/hora pode ser ajustado por geração se um controle mais específico for necessário.

De acordo com as regras de geração padrão, uma data que representasse o 22º dia do 5º mês do ano de 1998 geraria "May 22, 1998" em inglês (Estados Unidos), "22 May 1998" em inglês (Reino Unido), "22 mai 1998" em francês e "٢٢‏/٠٥‏/١٩٩٨" em árabe.

Geração cronológica em C++

A geração cronológica em C++ é processada pelas funções a seguir.

A maioria das opções acima usa "EDateTimeStyle" para controlar a saída (o padrão é obtido na localidade ativa, mas pode ser definido como "short", "medium", "long" ou "full").

Geração cronológica em Blueprints

A geração cronológica em Blueprints é processada pelos nós a seguir.

Transformativa

A geração transformativa é usada para converter um texto em uma representação diferente de si. Por exemplo, você pode converter texto em minúsculas em maiúsculas ou converter texto em maiúsculas em minúsculas.

Geração transformativa em C++

A geração transformativa em C++ é processada pelas funções a seguir.

Geração transformativa em Blueprints

A geração transformativa em Blueprints é processada pelos nós a seguir.

Tabelas de strings

As tabelas de strings fornecem uma maneira de centralizar o texto localizado em um (ou vários) locais conhecidos e, em seguida, referência as entradas em uma tabela de strings de outros ativos ou código de forma robusta que permite a reutilização fácil de tabelas de strings localizadas de texto.

As tabelas de string podem ser definidas em C++, carregadas usando um arquivo CSV ou criadas como um ativo. Confira a página Tabelas de string para obter mais informações.

Empacotamento de valor de texto

Os valores de texto podem ser empacotados como strings sem perdas (usando "FTextStringHelper" ou o "ImportText" e as funções "ExportText" de "UTextProperty").

Os seguintes formatos são suportados:

Tabelas de dados

Uma causa comum de chaves com localização instáveis é a importação iterativa de strings brutas de um arquivo CSV para uma Data Table, pois isso gera a geração de uma nova chave após cada importação. Uma solução para isso é atribuir uma chave determinística ao texto importado após a importação, substituindo a função "OnPostDataImport" na estrutura de linha e chamando "FText::ChangeKey" para atribuir a nova chave.

Em geral, usamos o nome da tabela de dados como o namespace e uma combinação do nome da linha e do nome da propriedade como a chave. Por exemplo:

	voidFMyTableRow::OnPostDataImport(constUDataTable*InDataTable,constFNameInRowName,TArray&OutCollectedImportProblems)
	{
	#if WITH_EDITOR
		MyTextProperty = FText::ChangeKey(
		InDataTable->GetName(),
		FString::Printf(TEXT("%s_%s"),*InRowName.ToString(), GET_MEMBER_NAME_STRING_CHECKED(FMyTableRow,MyTextProperty)),
		MyTextProperty
		);
	#endif// WITH_EDITOR
	}

Copy full snippet

Dados poliglotas

Os dados poliglotas permitem que novos dados de localização sejam adicionados em tempo de execução, seja para fazer a interface com um sistema externo ou para permitir a localização com hotfixing sem criar novos arquivos "LocRes".

Dados poliglotas são formados por: um namespace e uma key (identidade); uma string nativa; a categoria do texto (como jogo, engine, editor) que controlará quando os dados poliglotas serão usados; uma cultura nativa opcional (que retorna para a cultura nativa da categoria se não for definida); e uma série de traduções por cultura.

Dados poliglotas em C++

Dados poliglotas em C++ são representados pelo tipo "FPolyglotTextData" e podem ser usados diretamente (com "FPolyglotTextData::GetText" para resolver os dados poliglotas em uma instância de texto), ou serem passados para o nó "FTextLocalizationManager::RegisterPolyglotTextData" (para corrigir entradas de texto existentes).

Dados poliglotas em Blueprints

Dados poliglotas em Blueprints são representados pelo tipo Polyglot Text Data e podem ser usados com a função Polyglot Data to Text para transformar os dados poliglotas em uma instância de texto.

Fontes de textos localizados

As fontes de texto localizados são a principal forma usada pelo gerenciador de localização de texto da UE para descobrir e processar dados de texto localizados. A UE fornece dois desses por padrão: "FLocalizationResourceTextSource" (que hospeda o suporte "LocRes") e "FPolyglotTextSource" (que hospeda o suporte a dados poliglotas).

Fontes de texto localizados podem fornecer uma maneira de interagir com um sistema externo e podem ser adicionadas a cada projeto. Para isso, crie e registre um tipo derivado de "ILocalizedTextSource".