Miten toteuttaa monikielisyys Next.js-sovelluksessa, joka käyttää App Router -reititintä

Maailman globalisoituessa on yhä tärkeämpää, että verkkokehittäjät rakentavat sovelluksia, jotka voivat palvella käyttäjiä eri maista ja kulttuureista. Yksi keskeinen tapa saavuttaa tämä on kansainvälistäminen (i18n), joka mahdollistaa sovelluksen mukauttamisen eri kielille, valuutoille ja päivämäärämuodoille.

Tässä artikkelissa tutustumme siihen, kuinka lisätä kansainvälistäminen 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 App Router-reititintä.
Jos käytät Pages Router-reititintä, katso sen sijaan tämä opas.

Vaihe 1: Asenna i18n-kirjasto

Jotta voit toteuttaa kansainvälistämisen Next.js-sovelluksessasi, valitsemme ensin i18n-kirjaston. On useita suosittuja kirjastoja, mukaan lukien next-intl. Tässä esimerkissä käytämme kuitenkin TacoTranslate.

TacoTranslate kääntää merkkijonosi automaattisesti mihin tahansa kieleen käyttämällä huipputason tekoälyä, ja vapauttaa sinut JSON-tiedostojen tylsästä hallinnasta.

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-tili, 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 read avain ja yksi read/write avain. Tallennamme ne ympäristömuuttujiksi. read avainta kutsumme public eli julkiseksi ja read/write avainta secret eli salaiseksi. Voit esimerkiksi lisätä ne .env tiedostoon projektisi juureen.

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 varamuotokoodi. Tässä esimerkissä asetamme sen arvoksi en englannille.
• TACOTRANSLATE_ORIGIN: ”Kansio”, johon merkkijonosi tallennetaan, kuten verkkosivustosi URL-osoite. Lue lisää alkuperäisistä täältä.

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

Vaihe 3: TacoTranslate:n käyttöönotto

Integroinnin TacoTranslate sovellukseesi, sinun tulee luoda asiakas käyttäen aiemmin saatua 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Määrittelemme pian automaattisesti TACOTRANSLATE_API_KEY ja TACOTRANSLATE_PROJECT_LOCALE.

Asiakasohjelman luominen erilliseen tiedostoon tekee siitä helpon käyttää myöhemmin uudestaan. getLocales on vain apufunktio, jossa on sisäänrakennettu virheenkäsittelyä. Luo nyt tiedosto nimeltä /app/[locale]/tacotranslate.tsx, johon toteutamme TacoTranslate -providerin.

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Huomaa 'use client';, joka ilmaisee, että tämä on asiakaspuolen komponentti.

Nyt kun kontekstin tarjoaja on valmis, luo tiedosto nimeltä /app/[locale]/layout.tsx, sovelluksemme juurilayout. Huomaa, että tässä polussa on kansio, joka käyttää Dynamic Routes, jossa [locale] on dynaaminen parametri.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

Ensimmäinen asia, joka on syytä huomioida, on että käytämme Dynamic Route -parametriamme [locale] hakemaan käännökset kyseiselle kielelle. Lisäksi generateStaticParams varmistaa, että kaikki projektillesi aktivoidut kielikoodit esirendataan.

Rakennetaan nyt ensimmäinen sivumme! Luo tiedosto nimeltä /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

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

Huomaa revalidate muuttuja, joka kertoo Next.js:lle rakentaa sivu uudelleen 60 sekunnin välein ja pitää käännöksesi ajan tasalla.

Vaihe 4: Palvelinpuolen renderöinnin toteutus

TacoTranslate tukee palvelinpuolen renderöintiä. Tämä parantaa käyttäjäkokemusta huomattavasti näyttämällä käännetyn sisällön välittömästi sen sijaan, että ensin näkyisi hetken aikaa kääntämätöntä sisältöä. Lisäksi voimme ohittaa verkon pyynnöt asiakkaalla, koska meillä on jo käytettävissä ne käännökset, joita käyttäjän katsomalle sivulle tarvitaan.

Palvellinpuolen renderöinnin määrittämiseksi luo tai muokkaa /next.config.js:

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

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			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'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Muokkaa isProduction -tarkistusta vastaamaan omaa ympäristöäsi. Jos true, TacoTranslate näyttää julkisen API-avaimen. Jos olemme paikallisessa, testaus- 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.

Varmistaaksemme, että reititys ja uudelleenohjaukset toimivat odotetusti, meidän täytyy luoda tiedosto nimeltä /middleware.ts. Käyttämällä Middleware, voimme ohjata käyttäjät heidän suosimallaan kielellä esitettyihin sivuihin.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

export const config = {
	matcher: ['/((?!api|_next|favicon.ico).*)'],
};

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Varmista, että olet määrittänyt matcher sopimaan Next.js Middleware -dokumentaation mukaisesti.

Asiakaspuolella voit muuttaa locale evästettä (cookie) vaihtaaksesi käyttäjän toivomaa kieltä. Katso ideoita siitä, kuinka tämä tehdään, kokonaisesta esimerkkikoodista!

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

Olemme valmiit! React-sovelluksesi käännetään nyt automaattisesti, kun lisäät merkkijonoja Translate -komponenttiin. Huomaa, että vain ympäristöt, joilla on read/write -oikeudet API-avaimeen, pystyvät luomaan uusia käännettäviä merkkijonoja. Suosittelemme, että sinulla on suljettu ja suojattu staging-ympäristö, jossa voit testata tuotantosovellustasi tällaisen API-avaimen kanssa ja lisätä uusia merkkijonoja ennen julkaisua. Tämä estää ketään varastamasta salaista API-avaintasi ja mahdollisesti paisuttamasta käännösprojektiasi lisäämällä uusia, asiaankuulumattomia merkkijonoja.

Muista tarkistaa täydellinen esimerkki GitHub-profiilistamme. Sieltä löydät myös esimerkin siitä, miten tämä tehdään käyttäen Pages Routeria! Jos kohtaat ongelmia, ota vapaasti yhteyttä, niin autamme mielellämme.

TacoTranslate mahdollistaa React-sovellustesi automaattisen lokalisoimisen nopeasti mihin tahansa kieleen ja sieltä takaisin. Aloita jo tänään!