Documentação: Utilizar o TacoTranslate

A usar o TacoTranslate

Portuguese (Portugal)

A traduzir strings

Existem atualmente três formas de traduzir strings: o componente Translate, o hook useTranslation ou a ferramenta translateEntries.

Usar o componente Translate.
Produz 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 utilizando, por exemplo, as="p" no componente.

Usar o hook useTranslation.
Retorna traduções como uma cadeia de texto simples. Útil, por exemplo, em etiquetas 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>
	);
}

Usar a utilidade translateEntries.
Traduza strings 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 validamo-las e guardamo-las, depois retornamos imediatamente uma tradução automática. Embora as traduções automáticas sejam geralmente de qualidade inferior em comparação com as nossas traduções de IA, elas fornecem uma resposta inicial rápida.

Simultaneamente, iniciamos uma tarefa de tradução assíncrona para gerar uma tradução de alta qualidade, com inteligência artificial de última geração, para a sua cadeia de texto. Assim que a tradução com IA estiver pronta, ela substituirá a tradução automática e será enviada sempre que solicitar traduções para as suas cadeias de texto.

Se tiver traduzido manualmente uma string, essas traduções têm prioridade e serão retornadas em vez disso.

Utilização de origens

Os projetos TacoTranslate contêm o que chamamos de origens. Pense nelas 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-lhe separar strings em contentores significativos. Por exemplo, poderia ter uma origem para a documentação e outra para a sua página de marketing.

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

Para conseguir isto, 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 strings em origins depende de si e das suas necessidades. No entanto, note que ter muitas strings numa única origin pode aumentar os tempos de carregamento.

Gestão de variáveis

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

As variáveis nas 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 padrão, o componente Translate suporta e renderiza conteúdo HTML. No entanto, pode optar por não utilizar este comportamento definindo useDangerouslySetInnerHTML como false.

Desativar a renderização de HTML é fortemente recomendado ao traduzir conteúdos não confiáveis, como conteúdo gerado por utilizadores.

Toda a saída é sempre saneada com sanitize-html antes de ser apresentada.

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á renderizado como texto simples.

Renderização do lado do servidor