Kuinka toteuttaa kansainvälistäminen Next.js-sovelluksessa, joka käyttää App Routeria

Maailman muuttuessa yhä globaalimmaksi, on yhä tärkeämpää, että verkkokehittäjät rakentavat sovelluksia, jotka pystyvät palvelemaan käyttäjiä eri maista ja kulttuureista. Yksi keskeinen tapa saavuttaa tämä on kansainvälistäminen (i18n), jonka avulla voit mukauttaa sovelluksesi eri kielille, valuutoille ja päivämäärämuodoille.

Tässä artikkelissa tutustumme siihen, miten lisätä kansainvälistäminen React Next.js -sovellukseesi, jossa käytetään palvelinpuolen renderöintiä. TL;DR: Katso koko esimerkki tästä.

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

Internationalisoinnin toteuttamiseksi Next.js-sovelluksessasi valitsemme ensin i18n-kirjaston. On olemassa useita suosittuja kirjastoja, mukaan lukien next-intl. Tässä esimerkissä kuitenkin käytämme TacoTranslate.

TacoTranslate kääntää merkkijonosi automaattisesti mille tahansa kielelle huipputeknologian AI:n avulla, ja vapauttaa sinut JSON-tiedostojen hankalasta hallinnasta.

Asennetaan se käyttämällä npm komentorivilläsi:

npm install tacotranslate

Vaihe 2: Luo ilmainen TacoTranslate-tili

Nyt kun moduuli on asennettu, on aika luoda TacoTranslate-tilisi, käännösprojekti ja siihen liittyvät API-avaimet. Luo tili täällä. 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 -avain on se, mitä kutsumme public -avaimeksi, ja read/write -avain on secret. Voit esimerkiksi lisätä ne projektisi juureen sijaitsevaan .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: Oletuksena käytettävä varakielikoodi. Tässä esimerkissä asetamme sen arvoon en, eli englanti.
• TACOTRANSLATE_ORIGIN: ”Kansio”, johon merkkijonosi tallennetaan, esimerkiksi verkkosivustosi URL-osoite. Lue lisää origen-kohdasta täältä.

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

Vaihe 3: TacoTranslatein käyttöönotto

TacoTranslate integroimiseksi sovellukseesi sinun tulee luoda client 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_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Määrittelemme pian automaattisesti TACOTRANSLATE_API_KEY ja TACOTRANSLATE_PROJECT_LOCALE.

Asiakkaan luominen erilliseen tiedostoon tekee sen myöhemmästä uudelleenkäytöstä helppoa. getLocales on vain apufunktio, jossa on sisäänrakennettua 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.

Kun kontekstin tarjoaja on nyt valmis, luo tiedosto nimeltä /app/[locale]/layout.tsx, joka on 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 kannattaa huomioida, on että käytämme Dynamic Route -parametria [locale], hakeaksemme käännökset tälle kielelle. Lisäksi generateStaticParams varmistaa, että kaikki projektissasi aktivoidut lokaalikoodeista tehdään esirenderöinnit.

Nyt rakennetaan 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 kuluttua 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 välähdys kääntämättömästä sisällöstä. Lisäksi voimme ohittaa verkkopyynnöt asiakkaalla, koska meillä on jo tarvittavat käännökset käyttäjän katsomalle sivulle.

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 asetukseesi sopivaksi. Jos true, TacoTranslate tuo esiin julkisen API-avaimen. Jos olemme paikallisessa, testi- tai valmisteluympäristössä (isProduction is false), käytämme salaista read/write API-avainta varmistaaksemme, että uudet merkkijonot lähetetään käännettäväksi.

Varmistaaksemme, että reititys ja uudelleenohjaus toimivat odotetusti, meidän täytyy luoda tiedosto nimeltä /middleware.ts. Käyttämällä Middleware, voimme ohjata käyttäjät sivuille, jotka esitetään heidän mieluisalla kielellään.

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ä matcher on asetettu Next.js Middleware -dokumentaation mukaisesti.

Asiakaspuolella voit muuttaa locale evästettä vaihtaaksesi käyttäjän mieluisan kielen. Katso täydelliset esimerkkikoodit ideoita varten siihen, miten tämä tehdään!

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ä ainoastaan ympäristöt, joilla on read/write -oikeudet API-avaimeen, pystyvät luomaan uusia käännettäviä merkkijonoja. Suosittelemme pitämään suljetun ja suojatun staging-ympäristön, jossa voit testata tuotantosovellustasi tällaisella API-avaimella ja lisätä uusia merkkijonoja ennen julkaisua. Tämä estää ketään varastamasta salassa pidettävää 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!