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

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

Tässä artikkelissa tutkimme, kuinka lisätä kansainvälistäminen React Next.js -sovellukseesi palvelinpuolen renderöinnillä. 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

Kansainvälistämisen (i18n) toteuttamiseksi Next.js-sovelluksessasi valitsemme ensin i18n-kirjaston. Saatavilla on useita suosittuja kirjastoja, mukaan lukien next-intl. Tässä esimerkissä käytämme kuitenkin TacoTranslate.

TacoTranslate kääntää automaattisesti merkkijonosi mihin tahansa kieleen huippuluokan tekoälyn avulla ja vapauttaa sinut JSON-tiedostojen hankalasta hallinnasta.

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

npm install tacotranslate

Vaihe 2: Luo ilmainen TacoTranslate-tili

Nyt kun moduuli on asennettu, on aika luoda oma 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 eli julkiseksi ja read/write -avainta secret eli salaiseksi. 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: Oletusarvoinen varakieli. Tässä esimerkissä asetamme sen arvoon en englanniksi.
• TACOTRANSLATE_ORIGIN: ”Kansio”, johon merkkijonosi tallennetaan, esimerkiksi verkkosivustosi URL-osoite. Lue lisää origineista täältä.

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

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

Jotta voit integroida TacoTranslate-sovelluksesi kanssa, sinun täytyy luoda asiakas käyttäen 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.

Asiakasohjelman luominen erilliseen tiedostoon helpottaa sen uudelleenkäyttöä myöhemmin. getLocales on vain apufunktio, jossa on sisäänrakennettu virheenkäsittely. Luo nyt tiedosto nimeltä /app/[locale]/tacotranslate.tsx, jossa 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 osoittaa, että tämä on asiakaspuolen komponentti.

Kun kontekstin tarjoaja on nyt valmis, luo tiedosto nimeltä /app/[locale]/layout.tsx, joka on sovelluksemme juuriasettelu. 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 se, että käytämme Dynamic Route -parametria [locale] hakeaksemme kyseisen kielen käännökset. Lisäksi generateStaticParams varmistaa, että kaikki projektiisi aktivoidut kielikoodit esirenderöidään.

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 merkittävästi näyttämällä käännetyn sisällön heti, sen sijaan että ensin näkyisi välähtävä hetki kääntämätöntä sisältöä. Lisäksi voimme ohittaa verkkopyynnöt asiakkaalla, koska meillä on jo tarvittavat käännökset käyttäjän katsomalle sivulle.

Palvelinpuolen renderöinnin asettamiseksi 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 tulee luoda tiedosto nimeltä /middleware.ts. Käyttämällä Middleware-järjestelmää voimme ohjata käyttäjät heidän mieluisaksi kieleksi valituille sivuille.

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

Asiakkaalla voit muuttaa locale evästettä vaihtaaksesi käyttäjän mieltymyssuomen kieltä. Katso kokonainen esimerkkikoodi ideoita varten, 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ä vain ympäristöt, joilla on read/write -oikeudet API-avaimeen, pystyvät luomaan uusia käännettäviä merkkijonoja. Suosittelemme suljettua ja suojattua staging-ympäristöä, jossa voit testata tuotantosovellustasi tällaisella API-avaimella 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.

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!