Paano ipatupad ang internationalization sa isang Next.js na aplikasyon na gumagamit ng App Router

Habang nagiging mas globalisado ang mundo, lalong nagiging mahalaga para sa mga web developer na bumuo ng mga aplikasyon na maaaring magsilbi sa mga gumagamit mula sa iba't ibang bansa at kultura. Isa sa mga pangunahing paraan para makamit ito ay sa pamamagitan ng internationalization (i18n), na nagpapahintulot sa iyo na iangkop ang iyong aplikasyon sa iba't ibang wika, pera, at format ng petsa.

Sa artikulong ito, susuriin natin kung paano idagdag ang internationalization sa iyong React Next.js na aplikasyon, kasama ang server-side rendering. TL;DR: Tingnan ang buong halimbawa dito.

Ang gabay na ito ay para sa mga aplikasyon ng Next.js na gumagamit ng App Router.
Kung gumagamit ka ng Pages Router, tingnan ang gabay na ito sa halip.

Hakbang 1: Mag-install ng isang i18n library

Upang ipatupad ang internationalization sa iyong Next.js na aplikasyon, unang pipiliin namin ang isang i18n library. May ilang kilalang library, kabilang ang next-intl. Sa halimbawang ito, gayunpaman, gagamitin namin ang TacoTranslate.

Awtomatikong isinasalin ng TacoTranslate ang iyong mga string sa anumang wika gamit ang makabagong AI, at pinapalaya ka nito mula sa nakakapagod na pamamahala ng mga JSON file.

I-install natin ito gamit ang npm sa iyong terminal:

npm install tacotranslate

Hakbang 2: Lumikha ng libreng account sa TacoTranslate

Ngayon na na-install mo na ang module, oras na para lumikha ng iyong TacoTranslate account, isang proyekto ng pagsasalin, at mga kaugnay na API key. Gumawa ng account dito. Libre ito, at hindi kinakailangan magdagdag ng credit card.

Sa UI ng TacoTranslate, lumikha ng isang proyekto at pumunta sa tab ng mga API key nito. Lumikha ng isang read key, at isang read/write key. Ise-save namin ang mga ito bilang mga environment variable. Ang read key ang tinatawag nating public, at ang read/write key naman ay secret. Halimbawa, maaari mong idagdag ang mga ito sa isang .env file sa root ng iyong proyekto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Tiyaking huwag kailanman ibunyag ang lihim na read/write API key sa mga production environment sa client-side.

Magdaragdag din tayo ng dalawang karagdagang environment variable: TACOTRANSLATE_DEFAULT_LOCALE at TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Ang default na fallback na locale code. Sa halimbawang ito, itatak namin ito sa en para sa Ingles.
• TACOTRANSLATE_ORIGIN: Ang “folder” kung saan ilalagay ang iyong mga string, tulad ng URL ng iyong website. Basahin pa tungkol sa mga origin dito.

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

Hakbang 3: Pagsasaayos ng TacoTranslate

Upang maisama ang TacoTranslate sa iyong aplikasyon, kailangan mong lumikha ng isang client gamit ang mga API key na nabanggit kanina. Halimbawa, gumawa ng isang file na pinangalanang /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;

Awtomatikong itatakda namin ang TACOTRANSLATE_API_KEY at TACOTRANSLATE_PROJECT_LOCALE sa lalong madaling panahon.

Ang paggawa ng client sa isang hiwalay na file ay nagpapadali na magamit muli ito sa hinaharap. getLocales ay isang utility function lamang na may ilang built-in na paghahawak ng mga error. Ngayon, gumawa ng isang file na pinangalanang /app/[locale]/tacotranslate.tsx, kung saan ipapatupad natin ang 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>
	);
}

Pansinin ang 'use client'; na nagpapahiwatig na ito ay isang client component.

Ngayon na handa na ang context provider, gumawa ng isang file na pinangalanang /app/[locale]/layout.tsx, ang pangunahing layout sa aming aplikasyon. Tandaan na ang path na ito ay may folder na gumagamit ng Dynamic Routes, kung saan [locale] ay ang dynamic na parameter.

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

Ang unang bagay na dapat tandaan dito ay ginagamit natin ang ating parameter na Dynamic Route na [locale] upang kunin ang mga pagsasalin para sa wikang iyon. Dagdag pa, tinitiyak ng generateStaticParams na naka-pre-render ang lahat ng mga locale code na pinagana sa iyong proyekto.

Ngayon, buuin natin ang ating unang pahina! Gumawa ng isang file na pinangalanang /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!" />
	);
}

Pansinin ang revalidate variable na nagsasabi sa Next.js na muling buuin ang pahina pagkatapos ng 60 segundo, at panatilihing napapanahon ang iyong mga pagsasalin.

Hakbang 4: Pagpapatupad ng rendering sa server

Sinusuportahan ng TacoTranslate ang pag-render sa server. Malaki ang pagpapabuti nito sa karanasan ng gumagamit dahil agad na ipinapakita ang isinaling nilalaman, sa halip na magpakita muna ng panandaliang hindi pa isinaling nilalaman. Bukod pa rito, maaari nating laktawan ang mga kahilingan sa network mula sa kliyente, dahil mayroon na tayong mga pagsasaling kailangan para sa pahinang tinitingnan ng gumagamit.

Upang i-setup ang server-side rendering, gumawa o baguhin ang /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};
};

Baguhin ang isProduction na tsek upang umangkop sa iyong setup. Kung true, ipapakita ng TacoTranslate ang publikong API key. Kung tayo ay nasa lokal, test, o staging na environment (isProduction is false), gagamitin namin ang lihim na read/write API key upang matiyak na maipapadala ang mga bagong string para sa pagsasalin.

Upang matiyak na gumagana ang routing at pag-redirect ayon sa inaasahan, kailangan nating gumawa ng isang file na pinangalanang /middleware.ts. Sa pamamagitan ng Middleware, maaari nating i-redirect ang mga gumagamit sa mga pahinang ipinapakita sa kanilang nais na wika.

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

Siguraduhing i-set up ang matcher alinsunod sa Dokumentasyon ng Next.js Middleware.

Sa client, maaari mong baguhin ang cookie na locale upang baguhin ang ginustong wika ng gumagamit. Tingnan ang kumpletong halimbawa ng kodigo para sa mga ideya kung paano ito gawin!

Hakbang 5: I-deploy at subukan!

Tapos na kami! Awtomatikong maisasalin ang iyong React application kapag nagdagdag ka ng anumang mga string sa isang Translate component. Tandaan na tanging ang mga environment na may read/write na permiso sa API key ang makakalikha ng mga bagong string na isasalin. Inirerekomenda naming magkaroon ng isang sarado at seguradong staging environment kung saan maaari mong subukan ang iyong production application gamit ang ganoong API key, at magdagdag ng mga bagong string bago ilunsad. Hihinto nito ang sinuman sinuman mula sa pagnanakaw ng iyong lihim na API key, at potensyal na magdulot ng paglobo sa iyong proyekto ng pagsasalin sa pamamagitan ng pagdaragdag ng mga bagong, hindi kaugnay na string.

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!