Documentação: Utilizar o TacoTranslate

Utilizar o TacoTranslate

Portuguese (Portugal)

Tradução de strings

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

Utilização do componente Translate.
Exibe 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.

Utilização do useTranslation hook.
Devolve traduções como uma string 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>
	);
}

Usar a utilidade translateEntries.
Traduza cadeias de texto no servidor. Turbine 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 cadeias de caracteres são traduzidas

Quando as strings chegam aos nossos servidores, primeiro as validamos e as guardamos e, em seguida, devolvemos imediatamente 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 por IA, de alta qualidade e de última geração, para a sua string. Assim que a tradução por IA estiver pronta, ela substituirá a tradução automática e será enviada sempre que solicitar traduções para as suas strings.

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

Utilizar origens

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

import {TacoTranslate} from 'tacotranslate/react';

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

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

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

Para conseguir isto, considere utilizar vários fornecedores TacoTranslate no seu projeto.

Tenha em atenção que a mesma string pode receber traduções diferentes em origens diferentes.

Em última análise, a forma como separa strings em origins depende de si e das suas necessidades. No entanto, note que ter muitas strings num único origin pode aumentar os tempos de carregamento.

Manipulação de variáveis

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

As variáveis nas strings são declaradas usando chaves duplas, 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 usar este comportamento definindo useDangerouslySetInnerHTML para false.

Recomenda-se vivamente desativar a renderização HTML ao traduzir conteúdo não confiável, como conteúdo gerado pelos utilizadores.

Toda a saída é sempre sanitizada com sanitize-html antes de ser renderizada.

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