Documentació: Com utilitzar TacoTranslate

Ús de TacoTranslate

Catalan

Traducció de cadenes

Actualment hi ha tres maneres de traduir cadenes: el component Translate, el hook useTranslation, o la utilitat translateEntries.

Ús del component Translate.
Mostra les traduccions dins d'un element span, i admet el renderitzat de HTML.

import {Translate} from 'tacotranslate/react';

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

Pots canviar el tipus d'element, per exemple, fent servir as="p" en el component.

Ús del hook useTranslation.
Retorna les traduccions com una cadena de text simple. Útil, per exemple, en etiquetes 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>
	);
}

Ús de la utilitat translateEntries.
Traduir cadenes al costat del servidor. Potencia les teves imatges 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)
	};
}

Quan les cadenes arriben als nostres servidors, primer les validem i les guardem, i tot seguit retornem immediatament una traducció automàtica. Tot i que les traduccions automàtiques solen ser de qualitat inferior en comparació amb les nostres traduccions d'IA, ofereixen una resposta inicial ràpida.

Simultàniament, iniciem una tasca de traducció asincrònica per generar una traducció d'IA d'alta qualitat i d'avantguarda per a la vostra cadena. Un cop la traducció d'IA estigui llesta, substituirà la traducció automàtica i s'enviarà cada vegada que sol·liciteu traduccions per a les vostres cadenes.

Si heu traduït manualment una cadena, aquestes traduccions tenen preferència i es retornen en el seu lloc.

Ús d'orígens

Els projectes TacoTranslate contenen allò que anomenem orígens. Considereu-los com a punts d'entrada, carpetes o grups per a les vostres cadenes i traduccions.

import {TacoTranslate} from 'tacotranslate/react';

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

Els orígens us permeten separar les cadenes en contenidors significatius. Per exemple, podríeu tenir un origen per a la documentació i un altre per a la vostra pàgina de màrqueting.

Per a un control més granular, podríeu configurar origens a nivell de component.

Per aconseguir-ho, considera utilitzar diversos proveïdors de TacoTranslate dins del teu projecte.

Tingueu en compte que la mateixa cadena pot rebre traduccions diferents segons l'origen.

En última instància, la manera com separis les cadenes en orígens depèn de tu i de les teves necessitats. Tanmateix, tingues en compte que tenir moltes cadenes dins d'un mateix origen pot augmentar els temps de càrrega.

Gestió de variables

Sempre hauríeu d'utilitzar variables per a contingut dinàmic, com ara noms d'usuari, dates, adreces de correu electrònic i més.

Les variables a les cadenes es declaren amb claus dobles, com {{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}});
}

Gestió del contingut HTML

Per defecte, el component Translate admet i mostra contingut HTML. Tanmateix, pots desactivar aquest comportament configurant useDangerouslySetInnerHTML a false.

Es recomana fermament desactivar el renderitzat d'HTML quan es tradueix contingut no fiable, com el contingut generat per usuaris.

Tota la sortida sempre es neteja amb sanitize-html abans de ser renderitzada.

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

L'exemple anterior es mostrarà com a text pla.

Renderització del costat del servidor

Ús de TacoTranslate

Com es tradueixen les cadenes

Ús d'orígens

Gestió de variables

Gestió del contingut HTML