Paano mag-implement ng internationalization sa isang Next.js application na gumagamit ng App Router

Habang nagiging mas globalisado ang mundo, mas nagiging mahalaga para sa mga web developer ang bumuo ng mga aplikasyon na kayang tanggapin ang mga gumagamit mula sa iba't ibang bansa at kultura. Isa sa mga pangunahing paraan upang 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, tatalakayin natin kung paano magdagdag ng internationalization sa iyong React Next.js na aplikasyon, gamit ang server side rendering. TL;DR: Tingnan ang buong halimbawa dito.

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

Hakbang 1: Mag-install ng i18n library

Upang ipatupad ang internationalization sa iyong Next.js application, pipiliin muna natin ang isang i18n library. May ilang mga sikat na library, kabilang ang next-intl. Sa halimbawa na ito, gayunpaman, gagamitin natin ang TacoTranslate.

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

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

npm install tacotranslate

Hakbang 2: Gumawa ng libreng TacoTranslate account

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

Sa loob ng UI ng TacoTranslate application, gumawa ng isang proyekto, at mag-navigate sa tab ng API keys nito. Gumawa ng isang read key, at isang read/write key. Ise-save natin ang mga ito bilang mga environment variable. Ang read key ay tinatawag nating public, at ang read/write key ay secret. Halimbawa, maaari mo itong idagdag sa isang .env file sa root ng iyong proyekto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Siguraduhing huwag kailanman isiwalat ang secret read/write API key sa client side production environments.

Magdaragdag din tayo ng dalawang environment variables pa: TACOTRANSLATE_DEFAULT_LOCALE at TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Ang default na fallback locale code. Sa halimbawa na ito, itatakda natin ito sa en para sa Ingles.
• TACOTRANSLATE_ORIGIN: Ang “folder” kung saan imo-store ang iyong mga string, tulad ng URL ng iyong website. Magbasa pa tungkol sa origins dito.

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

Hakbang 3: Pagse-setup ng TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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 ito muli sa hinaharap. Ang getLocales ay isang utility function lamang na may kasamang built-in na paghawak ng 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, na siyang root layout sa aming aplikasyon. Tandaan na ang landas na ito ay may isang folder na gumagamit ng Dynamic Routes, kung saan ang [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 dapat tandaan dito ay ginagamit natin ang ating Dynamic Route parameter na [locale] upang kunin ang mga pagsasalin para sa wikang iyon. Bukod dito, tinitiyak ng generateStaticParams na lahat ng mga locale code na na-activate mo para sa iyong proyekto ay na-pre-render.

Ngayon, gawin 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 salin.

Hakbang 4: Pagpapatupad ng server side rendering

Sinusuportahan ng TacoTranslate ang server side rendering. Malaki ang pagpapabuti nito sa karanasan ng gumagamit sa pamamagitan ng pagpapakita ng isinaling nilalaman agad-agad, sa halip na munang ipakita ang isang flash ng hindi pa naisaling nilalaman. Bukod pa rito, maaari nating laktawan ang mga network request sa client, dahil mayroon na tayong mga pagsasalin na kailangan para sa pahinang tinitingnan ng gumagamit.

Para mag-setup ng 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 check upang umangkop sa iyong setup. Kung true, ipapakita ng TacoTranslate ang pampublikong API key. Kung kami ay nasa isang lokal, pagsubok, o staging na kapaligiran (isProduction is false), gagamitin namin ang lihim na read/write API key upang matiyak na ang mga bagong string ay ipinadala para sa pagsasalin.

Upang matiyak na gumagana nang maayos ang routing at redirection, kailangan nating gumawa ng isang file na pinangalanang /middleware.ts. Gamit ang Middleware, maaari nating i-redirect ang mga user 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 ayon sa dokumentasyon ng Next.js Middleware.

Sa client, maaari mong baguhin ang locale cookie upang palitan ang nais na wika ng gumagamit. Paki tingnan ang kumpletong halimbawa ng code para sa mga ideya kung paano ito gawin!

Hakbang 5: I-deploy at subukan!

Tapos na tayo! Ang iyong React application ay awtomatikong maisasalin kapag nagdagdag ka ng anumang mga string sa isang Translate na component. Tandaan na tanging mga environment na may read/write na mga pahintulot sa API key lamang ang makakalikha ng mga bagong string na isasalin. Inirerekomenda namin na magkaroon ng isang sarado at ligtas na staging environment kung saan maaari mong subukan ang iyong production application gamit ang ganitong API key, na nagdadagdag ng mga bagong string bago ito ilunsad. Ito ay makakaiwas sa sinuman na nakawin ang iyong lihim na API key, at posibleng mapalaki nang hindi kinakailangan ang iyong proyekto sa pagsasalin sa pamamagitan ng pagdagdag ng mga bagong, hindi kaugnay na mga string.

Siguraduhing tingnan ang kumpletong halimbawa sa aming GitHub profile. Doon, makakakita ka rin ng halimbawa kung paano gawin ito gamit ang Pages Router! Kung magkaroon ka ng anumang problema, huwag mag-atubiling makipag-ugnayan, at ikalulugod naming tulungan ka.

Pinapayagan ka ng TacoTranslate na awtomatikong i-localize ang iyong mga React application nang mabilis papunta at mula sa anumang wika. Magsimula na ngayon!