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.

Utilizar 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 utilizando, por exemplo, as="p" no componente.

Usar o useTranslation hook.
Retorna 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. 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 cadeias de texto chegam aos nossos servidores, primeiro as validamos e armazenamos, e depois devolvemos de imediato uma tradução automática. Embora as traduções automáticas sejam geralmente de qualidade inferior às nossas traduções geradas por IA, elas proporcionam 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 de IA estiver pronta, ela 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 serão devolvidas 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 cadeias de texto e traduções.

import {TacoTranslate} from 'tacotranslate/react';

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

As origens permitem separar strings 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 tal, considere usar vários fornecedores TacoTranslate no seu projeto.

Note que a mesma string pode receber traduções diferentes em origens diferentes.

Em última análise, a forma como separa as cadeias por origens depende de si e das suas necessidades. No entanto, tenha em atenção que ter muitas cadeias numa mesma 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 muito mais.

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 utilizar este comportamento definindo useDangerouslySetInnerHTML como false.

Recomenda-se vivamente desativar a renderização HTML ao traduzir conteúdo não confiável, como conteúdo gerado por 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á apresentado como texto simples.

Renderização no servidor