Documentação: Usar o TacoTranslate

Utilizar o TacoTranslate

Portuguese (Portugal)

A traduzir cadeias de texto

Atualmente, existem três formas de traduzir strings: o componente Translate, o hook useTranslation ou a utilidade translateEntries.

Usar o 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.

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

Utilizar a utilidade 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 cadeias de caracteres são traduzidas

Quando as strings chegam aos nossos servidores, primeiro as validamos e guardamos, e em seguida retornamos imediatamente uma tradução automática. Embora as traduções automáticas geralmente tenham uma qualidade inferior em comparação com as nossas traduções de 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 para as suas strings.

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

Utilizar origens

Os projetos TacoTranslate contêm o que chamamos de origins. Pense neles 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 cadeias de texto em contentores significativos. Por exemplo, pode ter uma origem para documentação e outra para a sua página de marketing.

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

Para conseguir isto, considere usar múltiplos fornecedores TacoTranslate no seu projeto.

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

Em última análise, a forma como separa as strings em origens depende de si e das suas necessidades. No entanto, note que ter muitas strings numa só origem 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 muito 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 predefinição, o componente Translate suporta e apresenta conteúdo HTML. No entanto, pode optar por não utilizar este comportamento definindo useDangerouslySetInnerHTML como false.

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

Todo o output é sempre sanitizado com sanitize-html antes de ser apresentado.

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 do lado do servidor