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

Maailman globalisoituessa verkkokehittä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ä artikkelissa käymme läpi, miten lisätä kansainvälistäminen React Next.js -sovellukseesi palvelinpuolen renderöinnillä. TL;DR: Katso täydellinen esimerkki täältä.

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

Vaihe 1: Asenna i18n-kirjasto

Toteuttaaksemme kansainvälistämisen Next.js-sovellukseesi valitsemme ensin i18n-kirjaston. On useita suosittuja kirjastoja, kuten next-intl. Tässä esimerkissä käytämme kuitenkin TacoTranslate.

TacoTranslate kääntää merkkijonosi automaattisesti mihin tahansa kieleen nykyaikaisen tekoälyn avulla ja vapauttaa sinut JSON-tiedostojen työläästä hallinnoinnista.

Asennetaan se terminaalissasi käyttäen npm:

npm install tacotranslate

Vaihe 2: Luo ilmainen TacoTranslate-tili

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 read -avain ja yksi read/write -avain. Tallennamme ne ympäristömuuttujiksi. read -avainta kutsumme public:ksi ja read/write -avainta kutsumme secret:ksi. Esimerkiksi voit 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: Oletusarvoinen varakielen paikalliskoodi. Tässä esimerkissä asetamme sen en:ksi (englanniksi).
• TACOTRANSLATE_ORIGIN: Se "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: TacoTranslaten käyttöönotto

TacoTranslaten 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.

Asiakasobjektin 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 asiakaskomponentti.

Kun kontekstin tarjoaja on nyt valmis, luo tiedosto nimeltä /app/[locale]/layout.tsx, joka on sovelluksemme juuriasettelu. Huomaa, että tämä polku sisältää kansion, 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 -parametriamme [locale] hakemaan käännöksiä kyseiselle kielelle. Lisäksi generateStaticParams varmistaa, että kaikki projektissasi 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 käskee Next.js:ää rakentamaan sivun uudelleen 60 sekunnin välein ja pitämään käännöksesi ajan tasalla.

Vaihe 4: Palvelinpuolen renderoinnin toteuttaminen

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ähtäisiin hetken ajan kääntämätöntä sisältöä. Lisäksi voimme ohittaa asiakaspuolen verkkopyynnöt, koska meillä on jo tarvittavat käännökset sille sivulle, jota käyttäjä tarkastelee.

Palvelinpuolen 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 asetuksiasi. 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äännöstä varten.

Varmistaaksemme, että reititys ja uudelleenohjaukset toimivat odotetusti, meidän on luotava tiedosto nimeltä /middleware.ts. Käyttämällä Middleware, voimme ohjata käyttäjiä sivuille, jotka esitetään heidän toivomallaan kielellä.

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

Asiakaspuolella voit muuttaa locale evästettä muuttaaksesi käyttäjän ensisijaista kieltä. Katso täydellinen esimerkkikoodi saadaksesi ideoita siitä, miten tehdä tämä!

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‑käyttöoikeudet API-avaimeen, pystyvät luomaan uusia käännettäviä merkkijonoja. Suosittelemme pitämään erillisen 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 ketään varastamasta salaista API‑avaintasi ja mahdollisesti paisuttamasta käännösprojektiasi lisäämällä uusia, siihen kuulumattomia 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 Pages 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!