Documentação: Utilização avançada

Utilização avançada

Portuguese (Portugal)

Lidar com idiomas da direita para a esquerda

TacoTranslate facilita o suporte a idiomas cuja escrita é da direita para a esquerda (RTL), como o árabe e o hebraico, nas suas aplicações React. O tratamento adequado desses idiomas garante que o seu conteúdo seja apresentado corretamente aos utilizadores que leem da direita para a esquerda.

import {useTacoTranslate} from 'tacotranslate/react';

function Document() {
	const {locale, isRightToLeft} = useTacoTranslate();

	return (
		<html lang={locale} dir={isRightToLeft ? 'rtl' : 'ltr'}>
			<body>
				// ...
			</body>
		</html>
	);
}

Também pode usar a função fornecida isRightToLeftLocaleCode para verificar a língua atual fora do React.

import {isRightToLeftLocaleCode} from 'tacotranslate';

function foo(locale = 'es') {
	const direction = isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr';
	// ...
}

Desativar a tradução

Para desativar a tradução de partes específicas de uma string ou para garantir que determinados segmentos sejam preservados tal como estão, pode utilizar colchetes triplos. Esta funcionalidade é útil para manter o formato original de nomes, termos técnicos ou qualquer outro conteúdo que não deva ser traduzido.

import {Translate} from 'tacotranslate/react';

function Component() {
	return (
		<Translate string="Hello, [[[TacoTranslate]]]!" />
	);
}

Neste exemplo, a palavra “TacoTranslate” permanecerá inalterada na tradução.

Vários provedores do TacoTranslate

Encorajamos vivamente a utilização de múltiplos TacoTranslate provedores na sua aplicação. Isto é útil para organizar as suas traduções e cadeias de texto em diferentes origens, como o cabeçalho, o rodapé ou secções específicas.

Pode ler mais sobre como utilizar origens aqui.

Os provedores TacoTranslate herdam as definições de qualquer provedor pai, por isso não terá de repetir outras definições.

import createTacoTranslateClient from 'tacotranslate';
import {TacoTranslate} from 'tacotranslate/react';

const tacoTranslateClient = createTacoTranslateClient({apiKey: 'YOUR_API_KEY'});

function Header() {
	return (
		<TacoTranslate origin="header">
			// ...
		</TacoTranslate>
	);
}

function Menu() {
	return (
		<TacoTranslate origin="menu">
			// ...
		</TacoTranslate>
	);
}

export default function App() {
	return (
		<TacoTranslate client={tacoTranslateClient} origin="page" locale="es">
			<Header />
			<Menu />
		</TacoTranslate>
	);
}

Anular origem ou localidade

Além de utilizar vários provedores TacoTranslate, também pode substituir tanto a origem como a localidade ao nível do componente Translate e do hook useTranslation.

import {Translate, useTranslation} from 'tacotranslate/react';

function Greeting() {
	const spanishHello = useTranslation('Hello!', {locale: 'es'});

	return (
		<>
			{spanishHello}
			<Translate string="What’s up?" origin="greeting" />
		</>
	);
}

Gestão do carregamento

Ao mudar o idioma no lado do cliente, a obtenção das traduções pode demorar alguns instantes, dependendo da ligação do utilizador. Pode mostrar um indicador de carregamento para melhorar a experiência do utilizador, fornecendo feedback visual durante a mudança.

import {useTacoTranslate} from 'tacotranslate/react';

function Component() {
	const {isLoading} = useTacoTranslate();

	return (
		isLoading ? 'Translations are loading...' : null
	);
}

Pluralização

Para lidar com a pluralização e exibir etiquetas baseadas em contagem corretamente em diferentes idiomas, isto é considerado uma boa prática:

import {Translate, useLocale} from 'tacotranslate/react';

function PhotoCount() {
	const locale = useLocale();
	const count = 1;

	return count === 0 ? (
		<Translate string="You have no photos." />
	) : count === 1 ? (
		<Translate string="You have 1 photo." />
	) : (
		<Translate
			string="You have {{count}} photos."
			variables={{count: count.toLocaleString(locale)}}
		/>
	);
}

Vários idiomas

Para suportar vários idiomas em simultâneo na mesma aplicação, pode usar vários fornecedores TacoTranslate com diferentes locale conforme mostrado abaixo:

Também pode sobrescrever o locale ao nível do componente ou do hook.

import createTacoTranslateClient from 'tacotranslate';
import {TacoTranslate, Translate} from 'tacotranslate/react';

const tacoTranslateClient = createTacoTranslateClient({apiKey: 'YOUR_API_KEY'});

function Spanish() {
	return (
		<TacoTranslate locale="es">
			<Translate string="Hello, world in Spanish!" />
		</TacoTranslate>
	);
}

function Norwegian() {
	return (
		<TacoTranslate locale="no">
			<Translate string="Hello, world in Norwegian!" />
		</TacoTranslate>
	);
}

export default function App() {
	return (
		<TacoTranslate client={tacoTranslateClient} origin="page" locale="es">
			<Spanish />
			<Norwegian />
		</TacoTranslate>
	);
}

Utilizar IDs de tradução

Pode adicionar um id ao componente Translate para tratar de traduções ou significados diferentes para o mesmo texto. Isto é particularmente útil quando o mesmo texto requer traduções diferentes consoante o contexto. Ao atribuir IDs únicos, garante que cada ocorrência do texto é traduzida com precisão de acordo com o seu significado específico.

import {Translate} from 'tacotranslate/react';

function Header() {
	return (
		<Translate id="header" string="Login" />
	);
}

function Footer() {
	return (
		<Translate id="footer" string="Login" />
	);
}

Por exemplo, o login no cabeçalho pode ser traduzido como “Iniciar sesión”, e o login no rodapé pode ser traduzido como “Acceder” em espanhol.

Boas práticas