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

Utilização avançada

Portuguese (Portugal)

Lidar com idiomas escritos da direita para a esquerda

TacoTranslate facilita o suporte a idiomas 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 a língua 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 cadeia de texto ou para garantir que determinados segmentos sejam preservados tal como estão, pode utilizar colchetes quadrados 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 TacoTranslate

Encorajamos vivamente a utilização de vários provedores TacoTranslate 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 saber mais sobre como utilizar origens aqui.

TacoTranslate provedores herdam as configurações de qualquer provedor pai, pelo que não terá de repetir quaisquer outras configuraçõ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>
	);
}

Sobrescrever origem ou localidade

Para além de usar múltiplos TacoTranslate provedores, pode também 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" />
		</>
	);
}

Gerir o carregamento

Ao mudar de idioma 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 alteração.

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 corretamente rótulos dependentes de contagem em diferentes línguas, considera-se esta 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 provedores TacoTranslate com diferentes valores de locale, como 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 gerir traduções diferentes ou significados distintos para a mesma cadeia de texto. Isto é particularmente útil quando o mesmo texto exige traduções diferentes consoante o contexto. Ao atribuir IDs únicos, garante que cada ocorrência da cadeia seja 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