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 escritos da direita para a esquerda (RTL), como o árabe e o hebraico, nas suas aplicações React. O tratamento adequado de idiomas RTL 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 o idioma atual fora do React.

import {isRightToLeftLocaleCode} from 'tacotranslate';

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

Desativar tradução

Para desativar a tradução de partes específicas de uma string ou para garantir que certos segmentos sejam preservados tal como estão, pode usar colchetes quadrados triplos. Esta funcionalidade é útil para manter o formato original de nomes, termos técnicos ou de 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 fornecedores do TacoTranslate

Recomendamos 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 fornecedores TacoTranslate herdam as definições de qualquer fornecedor pai, por isso não terá de repetir quaisquer 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 TacoTranslate provedores, também pode anular 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" />
		</>
	);
}

Gerir o carregamento

Ao alterar a língua no lado do cliente, a obtenção das traduções pode demorar alguns instantes, dependendo da ligação do utilizador. Pode apresentar 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 tratar a pluralização e apresentar rótulos baseados em contagens corretamente em diferentes línguas, 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 simultaneamente na mesma aplicação, pode usar vários fornecedores TacoTranslate com diferentes valores de locale como mostrado abaixo:

Também pode substituir 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 lidar com diferentes traduções ou significados da mesma cadeia de caracteres. Isto é particularmente útil quando o mesmo texto requer traduções diferentes consoante o contexto. Ao atribuir IDs únicos, garante que cada ocorrência da cadeia é 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 do cabeçalho pode ser traduzido como “Iniciar sesión”, e o login do rodapé pode ser traduzido como “Acceder” em espanhol.

Boas práticas