Documentação: Uso avançado

Uso avançado

Portuguese (Brazil)

Manipulando idiomas da direita para a esquerda

O TacoTranslate facilita o suporte a idiomas da direita para a esquerda (RTL), como árabe e hebraico, em suas aplicações React. O tratamento adequado dos idiomas RTL garante que seu conteúdo seja exibido corretamente para usuários 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>
	);
}

Você 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';
	// ...
}

Desabilitando a tradução

Para desativar a tradução de partes específicas de uma string ou garantir que certos segmentos sejam preservados como estão, você pode usar colchetes triplos. Esse recurso é útil para manter o formato original de nomes, termos técnicos ou qualquer outro conteúdo que não deve ser traduzido.

import {Translate} from 'tacotranslate/react';

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

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

Múltiplos provedores TacoTranslate

Incentivamos fortemente a utilização de múltiplos provedores TacoTranslate em seu aplicativo. Isso é útil para organizar suas traduções e strings em diferentes origens, como seu cabeçalho, rodapé ou seções específicas.

Você pode ler mais sobre como utilizar origens aqui.

Os provedores TacoTranslate herdam as configurações de qualquer provedor pai, então você não precisará repetir nenhuma outra configuração.

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>
	);
}

Substituindo origem ou localidade

Além de usar múltiplos provedores TacoTranslate, você também pode sobrescrever tanto a origem quanto a localidade nos níveis 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" />
		</>
	);
}

Manipulando o carregamento

Ao mudar de idioma no cliente, a busca pelas traduções pode levar alguns momentos dependendo da conexão do usuário. Você pode exibir um indicador de carregamento para melhorar a experiência do usuário, fornecendo um feedback visual durante a troca.

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 rótulos baseados em contagem corretamente em diferentes idiomas, esta é considerada 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)}}
		/>
	);
}

Múltiplos idiomas

Para suportar múltiplos idiomas simultaneamente dentro da mesma aplicação, você pode usar múltiplos provedores TacoTranslate com diferentes valores locale como mostrado abaixo:

Você também pode sobrescrever o locale no nível do componente ou 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>
	);
}

Usando IDs de tradução

Você pode adicionar um id ao componente Translate para lidar com diferentes traduções ou significados para a mesma string. Isso é particularmente útil quando o mesmo texto requer traduções diferentes com base no contexto. Ao atribuir IDs únicos, você garante que cada instância da string seja traduzida com precisão de acordo com 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.

Melhores práticas