Paras ratkaisu kansainvälistämiseen (i18n) Next.js-sovelluksissa

Miten se toimii

Kun maailma globalisoituu, web-kehittäjien on yhä tärkeämpää rakentaa sovelluksia, jotka palvelevat käyttäjiä eri maista ja kulttuureista. Yksi keskeisistä tavoista saavuttaa tämä on kansainvälistäminen (i18n), jonka avulla voit mukauttaa sovelluksesi eri kielille, valuutoille ja päivämäärämuodoille.

Tässä opetusohjeessa tutkimme, miten voit lisätä kansainvälistämisen React Next.js -sovellukseesi palvelinpuolen renderöinnillä. TL;DR: Katso koko esimerkki täältä.

Tämä opas on tarkoitettu Next.js-sovelluksille, jotka käyttävät Pages Router.
Jos käytät App Router, katso sen sijaan tämä opas.

Vaihe 1: Asenna i18n-kirjasto

Kansainvälistämisen toteuttamiseksi Next.js-sovelluksessasi valitsemme ensin i18n-kirjaston. Saatavilla on useita suosittuja kirjastoja, muun muassa next-intl. Kuitenkin tässä esimerkissä käytämme TacoTranslate.

TacoTranslate kääntää merkkijonosi automaattisesti mille tahansa kielelle huippuluokan tekoälyn avulla ja vapauttaa sinut JSON-tiedostojen työläästä hallinnoinnista.

Asennetaan se käyttämällä npm terminaalissasi:

npm install tacotranslate

Vaihe 2: Luo ilmainen TacoTranslate-tili

Nyt kun olet asentanut moduulin, on aika luoda TacoTranslate-tilisi, käännösprojekti ja siihen liittyvät API-avaimet. Luo tili tästä. Se on ilmaista, eikä vaadi luottokortin lisäämistä.

TacoTranslate-sovelluksen käyttöliittymässä luo projekti ja siirry sen API-avaimet-välilehdelle. Luo yksi avain tyypille read ja yksi avain tyypille read/write. Tallennamme ne ympäristömuuttujiin. Sitä avainta, jonka tyyppi on read, kutsumme public:ksi, ja sitä avainta, jonka tyyppi on read/write, kutsumme secret:ksi. Esimerkiksi voit lisätä ne projektisi juurihakemistossa olevaan .env tiedostoon.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Varmista, ettet koskaan vuoda salaista read/write API-avainta asiakaspuolen tuotantoympäristöihin.

Lisäämme myös kaksi muuta ympäristömuuttujaa: TACOTRANSLATE_DEFAULT_LOCALE ja TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Oletusarvoinen varakielen paikalliskoodi. Tässä esimerkissä asetamme sen arvoon en (englanti).
• TACOTRANSLATE_ORIGIN: "Kansio", johon merkkijonosi tallennetaan, esimerkiksi verkkosivustosi URL-osoite. Lue lisää originista täältä.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Vaihe 3: TacoTranslate-asetusten määrittäminen

TacoTranslaten integroimiseksi sovellukseesi sinun täytyy luoda asiakas käyttämällä aiemmin annettuja API-avaimia. Esimerkiksi luo tiedosto nimeltä /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY ??
		'',
	projectLocale: process.env.TACOTRANSLATE_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Määrittelemme TACOTRANSLATE_API_KEY automaattisesti pian.

Clientin luominen erilliseen tiedostoon tekee sen uudelleenkäytön myöhemmin helpommaksi. Nyt käyttäen mukautettua /pages/_app.tsx, lisäämme TacoTranslate providerin.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Jos sinulla on jo mukautetut pageProps ja _app.tsx, laajenna määrittelyä yllä olevilla ominaisuuksilla ja koodilla.

Vaihe 4: Palvelinpuolen renderöinnin toteuttaminen

TacoTranslate tukee käännösten palvelinpuolen renderöintiä. Tämä parantaa käyttäjäkokemusta merkittävästi näyttämällä käännetyn sisällön välittömästi sen sijaan, että ensin näkyisi hetken kääntämätöntä sisältöä. Lisäksi voimme ohittaa asiakaspuolen verkkopyynnöt, koska meillä on jo kaikki tarvitsemamme käännökset.

Aloitamme luomalla tai muokkaamalla /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		client: tacoTranslateClient,
		isProduction:
			process.env.TACOTRANSLATE_ENV === 'production' ||
			process.env.VERCEL_ENV === 'production' ||
			(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
				process.env.NODE_ENV === 'production'),
	});
};

Muokkaa isProduction tarkistusta vastaamaan asetuksiasi. Jos true, TacoTranslate näyttää julkisen API-avaimen. Jos olemme paikallisessa, testi- tai staging-ympäristössä (isProduction is false), käytämme salaista read/write API-avainta varmistaaksemme, että uudet merkkijonot lähetetään käännettäviksi.

Toistaiseksi olemme ainoastaan määrittäneet Next.js-sovellukselle luettelon tuetuista kielistä. Seuraavaksi haemme käännökset kaikille sivuillesi. Tätä varten käytät joko getTacoTranslateStaticProps tai getTacoTranslateServerSideProps tarpeidesi mukaan.

Nämä funktiot ottavat kolme argumenttia: yhden Next.js Static Props Context -objektin, TacoTranslate-konfiguraation ja valinnaiset Next.js-ominaisuudet. Huomaa, että revalidate kohdassa getTacoTranslateStaticProps on oletuksena asetettu arvoon 60, jotta käännöksesi pysyvät ajan tasalla.

Käyttääksesi jompaa kumpaa funktiota sivulla, oletetaan, että sinulla on sivutiedosto, kuten /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

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

Sinun pitäisi nyt pystyä käyttämään Translate-komponenttia kääntääksesi merkkijonoja kaikissa React-komponenteissasi.

import {Translate} from 'tacotranslate/react';

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

Vaihe 5: Ota käyttöön ja testaa!

Olemme valmiit! Next.js-sovelluksesi käännetään nyt automaattisesti, kun lisäät merkkijonoja Translate komponenttiin. Huomaa, että vain ympäristöt, joissa API-avaimella on read/write oikeudet, voivat luoda uusia käännettäviä merkkijonoja. Suosittelemme suljettua ja suojattua staging-ympäristöä, jossa voit testata tuotantosovellustasi kyseisellä API-avaimella ja lisätä uusia merkkijonoja ennen tuotantoon siirtymistä. Tämä estää ketään varastamasta salaista API-avaintasi ja mahdollisesti paisuttamasta käännösprojektiasi lisäämällä uusia, asiaankuulumattomia merkkijonoja.

Be sure to check out the complete example over at our GitHub profile. There, you’ll also find an example of how to do this using the App Router! If you encounter any problems, feel free to reach out, and we’ll be more than happy to help.

TacoTranslate lets you automatically localize your React applications quickly to and from over 75 languages. Get started today!