Kako implementirati internacionalizaciju u Next.js aplikaciji koja koristi App Router

Kako se svijet sve više globalizira, web programerima je sve važnije stvarati aplikacije koje mogu zadovoljiti korisnike iz različitih zemalja i kultura. Jedan od ključnih načina da se to postigne je internacionalizacija (i18n), koja vam omogućuje prilagodbu aplikacije različitim jezicima, valutama i formatima datuma.

U ovom ćemo članku istražiti kako dodati internacionalizaciju u vašu React Next.js aplikaciju uz renderiranje na strani poslužitelja. TL;DR: Pogledajte cijeli primjer ovdje.

Ovaj vodič je za Next.js aplikacije koje koriste App Router.
Ako koristite Pages Router, pogledajte umjesto toga ovaj vodič.

Korak 1: Instalirajte i18n knjižnicu

Za implementaciju internacionalizacije u vašoj Next.js aplikaciji, prvo ćemo odabrati i18n knjižnicu. Postoji nekoliko popularnih knjižnica, uključujući next-intl. U ovom primjeru, međutim, koristit ćemo TacoTranslate.

TacoTranslate automatski prevodi vaše tekstove na bilo koji jezik koristeći najsuvremeniju umjetnu inteligenciju i oslobađa vas zamornog upravljanja JSON datotekama.

Instalirajmo ga pomoću npm u vašem terminalu:

npm install tacotranslate

Korak 2: Stvorite besplatan TacoTranslate račun

Sad kad ste instalirali modul, vrijeme je da stvorite svoj TacoTranslate račun, projekt za prevođenje i pripadajuće API ključeve. Stvorite račun ovdje. Besplatno je i ne zahtijeva dodavanje kreditne kartice.

U korisničkom sučelju aplikacije TacoTranslate stvorite projekt i otvorite karticu API ključeva. Napravite jedan read ključ i jedan read/write ključ. Spremit ćemo ih kao varijable okruženja. Ključ read nazivamo public, a ključ read/write nazivamo secret. Na primjer, možete ih dodati u datoteku .env u korijenu vašeg projekta.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Pobrinite se da nikada ne otkrijete tajni read/write API ključ u produkcijskim okruženjima na strani klijenta.

Također ćemo dodati još dvije varijable okruženja: TACOTRANSLATE_DEFAULT_LOCALE i TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Zadani kod lokalizacije koji se koristi ako prijevod nije dostupan. U ovom primjeru postavit ćemo ga na en za engleski.
• TACOTRANSLATE_ORIGIN: „mapa” u kojoj će biti pohranjeni vaši stringovi, poput URL‑a vaše web-stranice. Saznajte više o originima ovdje.

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

Korak 3: Postavljanje TacoTranslatea

Da biste integrirali TacoTranslate u svoju aplikaciju, morat ćete stvoriti klijenta koristeći API ključeve iz prethodnog koraka. Na primjer, stvorite datoteku nazvanu /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;

Uskoro ćemo automatski definirati TACOTRANSLATE_API_KEY i TACOTRANSLATE_PROJECT_LOCALE.

Kreiranje klijenta u zasebnoj datoteci olakšava ponovno korištenje kasnije. getLocales je samo pomoćna funkcija s ugrađenom obradom pogrešaka. Sada stvorite datoteku nazvanu /app/[locale]/tacotranslate.tsx, u kojoj ćemo implementirati TacoTranslate provider.

'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>
	);
}

Obratite pozornost na 'use client'; koja označava da je ovo klijentska komponenta.

Budući da je kontekstni provider sada spreman, stvorite datoteku nazvanu /app/[locale]/layout.tsx, korijenski layout u našoj aplikaciji. Imajte na umu da ova putanja sadrži mapu koja koristi Dynamic Routes, gdje je [locale] dinamički parametar.

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>
	);
}

Prvo što treba napomenuti ovdje je da koristimo naš Dynamic Route parametar [locale] za dohvaćanje prijevoda za taj jezik. Osim toga, generateStaticParams osigurava da su svi kodovi lokaliteta koje ste aktivirali za svoj projekt pre-renderirani.

Sada ćemo izgraditi našu prvu stranicu! Stvorite datoteku nazvanu /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!" />
	);
}

Obratite pozornost na revalidate varijablu koja govori Next.js-u da ponovno izgradi stranicu nakon 60 sekundi i održava vaše prijevode ažurnima.

Korak 4: Implementacija renderiranja na strani poslužitelja

TacoTranslate podržava renderiranje na strani poslužitelja. To znatno poboljšava korisničko iskustvo jer se prevedeni sadržaj prikazuje odmah, umjesto prvotnog bljeska neprevedenog sadržaja. Dodatno, možemo preskočiti mrežne zahtjeve na klijentu, budući da već imamo prijevode potrebne za stranicu koju korisnik pregledava.

Da biste omogućili renderiranje na strani poslužitelja, stvorite ili izmijenite /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};
};

Prilagodite provjeru isProduction vašoj konfiguraciji. Ako je true, TacoTranslate će prikazati javni API ključ. Ako se nalazimo u lokalnom, testnom ili staging okruženju (isProduction is false), koristit ćemo tajni read/write API ključ kako bismo osigurali da se novi tekstovi pošalju na prijevod.

Da bismo osigurali da usmjeravanje i preusmjeravanje rade kako se očekuje, morat ćemo stvoriti datoteku nazvanu /middleware.ts. Korištenjem Middleware, možemo preusmjeravati korisnike na stranice prikazane na njihovom preferiranom jeziku.

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);
}

Pobrinite se da postavite matcher u skladu s dokumentacijom Next.js Middleware.

Na klijentskoj strani možete promijeniti kolačić locale kako biste promijenili preferirani jezik korisnika. Pogledajte cjeloviti primjer koda za ideje kako to napraviti!

Korak 5: Objavite i testirajte!

Gotovo! Vaša React aplikacija sada će se automatski prevoditi kad god dodate bilo koji string u komponentu Translate. Imajte na umu da samo okruženja koja imaju dopuštenja read/write na API ključu moći će stvarati nove stringove za prevođenje. Preporučujemo da imate zatvoreno i osigurano staging okruženje u kojem možete testirati svoju produkcijsku aplikaciju s takvim API ključem, dodajući nove stringove prije puštanja u produkciju. To će spriječiti bilo koga bilo koga da ukrade vaš tajni API ključ i te potencijalno napuhati vaš projekt prevođenja dodavanjem novih, nepovezanih stringova.

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!