Documentação: Como usar o TacoTranslate

Utilizar o TacoTranslate

Portuguese (Portugal)

Tradução de strings

Atualmente existem três formas de traduzir strings: o componente Translate, o hook useTranslation, ou o utilitário translateEntries.

Uso do componente Translate.
Apresenta traduções dentro de um elemento span e suporta a renderização de HTML.

import {Translate} from 'tacotranslate/react';

function Page() {
	return <Translate string="Hello, world!" />;
}

Pode alterar o tipo de elemento usando, por exemplo, as="p" no componente.

Usar o useTranslation hook.
Retorna as traduções como uma cadeia de caracteres simples. Útil, por exemplo, em tags meta.

import {useEffect} from 'react';
import {useTranslation} from 'tacotranslate/react';

function Page() {
	const helloWorld = useTranslation('Hello, world!');

	useEffect(() => {
		alert(helloWorld);
	}, [helloWorld]);

	return (
		<title>{useTranslation('My page title')}</title>
	);
}

Utilizando o utilitário translateEntries.
Traduza cadeias de caracteres no lado do servidor. Potencie as suas imagens OpenGraph.

import {createEntry, translateEntries} from 'tacotranslate';

async function generateMetadata(locale = 'es') {
	const title = createEntry({string: 'Hello, world!'});
	const description = createEntry({string: 'TacoTranslate on the server'});

	const translations = await translateEntries(
		tacoTranslate,
		{origin: 'opengraph', locale},
		[title, description]
	);

	return {
		title: translations(title),
		description: translations(description)
	};
}

Como as strings são traduzidas

Quando as strings chegam aos nossos servidores, primeiro as validamos e as guardamos, e depois devolvemos de imediato uma tradução automática. Embora as traduções automáticas sejam, em geral, de qualidade inferior às nossas traduções por IA, elas fornecem uma resposta inicial rápida.

Simultaneamente, iniciamos um trabalho de tradução assíncrono para gerar uma tradução de IA de alta qualidade e de última geração para a sua string. Assim que a tradução por IA estiver pronta, substituirá a tradução automática e será enviada sempre que solicitar traduções das suas strings.

Se tiver traduzido manualmente uma string, essas traduções têm precedência e são devolvidas em vez disso.

Utilizar origens

Os projetos TacoTranslate contêm aquilo a que chamamos origins. Considere-os como pontos de entrada, pastas ou grupos para as suas strings e traduções.

import {TacoTranslate} from 'tacotranslate/react';

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

As origens permitem separar cadeias de caracteres em contentores significativos. Por exemplo, poderá ter uma origem para a documentação e outra para a sua página de marketing.

Para um controlo mais granular, pode configurar origens ao nível do componente.

Para isso, considere usar vários fornecedores TacoTranslate no seu projeto.

Por favor, note que a mesma string pode receber traduções diferentes em origens distintas.

Em última análise, a forma como separa as cadeias de caracteres em origens depende de si e das suas necessidades. No entanto, note que ter muitas cadeias de caracteres numa única origem pode aumentar os tempos de carregamento.

Manipulação de variáveis

Deve sempre utilizar variáveis para conteúdo dinâmico, como nomes de utilizador, datas, endereços de e‑mail e outros.

As variáveis em strings são declaradas usando colchetes duplos, como {{variable}}.

import {Translate} from 'tacotranslate/react';

function Greeting() {
	const name = 'Juan';
	return <Translate string="Hello, {{name}}!" variables={{name}} />;
}

import {useTranslation} from 'tacotranslate/react';

function useGreeting() {
	const name = 'Juan';
	return useTranslation('Hello, {{name}}!', {variables: {name}});
}

Gestão de conteúdo HTML

Por predefinição, o componente Translate suporta e renderiza conteúdo HTML. No entanto, pode optar por não utilizar este comportamento definindo useDangerouslySetInnerHTML para false.

É altamente recomendável desativar a renderização HTML ao traduzir conteúdo não confiável, como conteúdo gerado pelos utilizadores.

Todas as saídas são sempre sanitizadas com sanitize-html antes de serem renderizadas.

import {Translate} from 'tacotranslate/react';

function Page() {
	return (
		<Translate
			string={`
				Welcome to <strong>my</strong> website.
				I’m using <a href="{{url}}">TacoTranslate</a> to translate text.
			`}
			variables={{url: 'https://tacotranslate.com'}}
			useDangerouslySetInnerHTML={false}
		/>
	);
}

O exemplo acima será apresentado como texto simples.

Renderização no lado do servidor