Paano ipatupad ang internasyonal na pag-aangkop (i18n) sa isang Next.js application na gumagamit ng Pages Router

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

Sa tutorial na ito, tatalakayin namin kung paano magdagdag ng internasyonal na pag-aangkop sa iyong React Next.js na aplikasyon, na may pag-render sa server. TL;DR: Tingnan ang buong halimbawa dito.

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

Hakbang 1: Mag-install ng isang i18n library

Upang ipatupad ang internationalization sa iyong Next.js application, pipiliin muna natin ang isang i18n na library. May ilang kilalang library, kabilang ang next-intl. Gayunpaman, sa halimbawang ito, gagamitin natin ang TacoTranslate.

Awtomatikong isinasalin ng TacoTranslate ang iyong mga string sa anumang wika gamit ang makabagong AI, at pinapalaya ka nito mula sa matrabahong 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 proyektong pagsasalin, at ang mga kaugnay na API key. Gumawa ng account dito. Libre ito, at hindi mo kailangang magdagdag ng credit card.

Sa UI ng TacoTranslate application, gumawa ng proyekto at pumunta 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 ang tinatawag nating public at ang read/write key ay secret. Halimbawa, maaari mo silang idagdag sa isang .env file sa root ng iyong proyekto.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

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

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

Hakbang 3: Pagsasaayos ng TacoTranslate

Upang i-integrate ang TacoTranslate sa iyong aplikasyon, kakailanganin mong gumawa ng client gamit ang mga API key mula 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Awtomatikong itatakda namin ang TACOTRANSLATE_API_KEY sa loob ng ilang sandali.

Ang paggawa ng kliyente sa isang hiwalay na file ay nagpapadali na magamit muli ito sa hinaharap. Ngayon, gamit ang isang custom /pages/_app.tsx, idaragdag natin ang TacoTranslate provider.

import React from 'react';
import {type AppProps} from 'next/app';
import {type Origin, type Locale, type Localizations} from 'tacotranslate';
import TacoTranslate from 'tacotranslate/react';
import TacoTranslateHead from 'tacotranslate/next/head';
import tacoTranslate from '../tacotranslate-client';

type PageProperties = {
	origin: Origin;
	locale: Locale;
	locales: Locale[];
	localizations: Localizations;
};

export default function App({Component, pageProps}: AppProps<PageProperties>) {
	const {origin, locale, locales, localizations} = pageProps;

	return (
		<TacoTranslate
			client={tacoTranslate}
			origin={origin}
			locale={locale}
			localizations={localizations}
		>
			<TacoTranslateHead rootUrl="https://your-website.com" locales={locales} />
			<Component {...pageProps} />
		</TacoTranslate>
	);
}

Kung mayroon ka nang pasadyang pageProps at _app.tsx, pakipalawakin ang depinisyon gamit ang mga property at code mula sa itaas.

Hakbang 4: Pagpapatupad ng server-side rendering

Pinapayagan ng TacoTranslate ang server-side rendering ng iyong mga pagsasalin. Malaki ang pinapabuti nito sa karanasan ng gumagamit dahil ipinapakita agad ang isinaling nilalaman, sa halip na magpakita muna ng sandaling hindi naisaling teksto. Dagdag pa rito, maaari nating laktawan ang mga network request sa client, dahil nasa atin na ang lahat ng kinakailangang pagsasalin.

Magsisimula tayo sa pamamagitan ng paggawa o pagbabago ng /next.config.js.

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = {};

	return withTacoTranslate(config, {
		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'),
	});
};

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

Hanggang ngayon, naitakda lamang natin ang Next.js application na may listahan ng mga sinusuportahang wika. Ang susunod na gagawin natin ay kukunin ang mga pagsasalin para sa lahat ng iyong mga pahina. Upang gawin iyon, gagamitin mo alinman ang getTacoTranslateStaticProps o getTacoTranslateServerSideProps batay sa iyong mga pangangailangan.

Ang mga function na ito ay tumatanggap ng tatlong argumento: isang Next.js Static Props Context na object, konfigurasyon para sa TacoTranslate, at mga opsyonal na properties ng Next.js. Tandaan na ang revalidate sa getTacoTranslateStaticProps ay naka-set sa 60 bilang default, upang manatiling napapanahon ang iyong mga pagsasalin.

Upang gamitin ang alinmang function sa isang pahina, ipagpalagay nating mayroon kang file ng pahina tulad ng /pages/hello-world.tsx.

import {Translate} from 'tacotranslate/react';
import getTacoTranslateStaticProps from 'tacotranslate/next/get-static-props';
import tacoTranslateClient from '../tacotranslate-client';

export async function getStaticProps(context) {
	return getTacoTranslateStaticProps(context, {client: tacoTranslateClient});
}

export default function Page() {
	return <Translate string="Hello, world!"/>;
}

Dapat ay maaari mo na ngayong gamitin ang Translate component para isalin ang mga string sa lahat ng iyong mga React component.

import {Translate} from 'tacotranslate/react';

function Component() {
	return <Translate string="Hello, world!"/>
}

Hakbang 5: I-deploy at subukan!

Tapos na! Awtomatikong maisasalin ang iyong React application kapag nagdagdag ka ng anumang mga string sa isang Translate component. Tandaan na tanging mga environment na may read/write na pahintulot sa API key ang makakalikha ng mga bagong string na isasalin. Inirerekomenda namin na 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 maging live. Mapipigilan nito ang sinuman sinuman na nakawin ang iyong lihim na API key, at potensyal na magpalobo ng iyong translation project sa pamamagitan ng pagdaragdag ng mga bagong, hindi kaugnay na string.

Tiyakin na tingnan ang kumpletong halimbawa sa aming GitHub profile. Doon, makakakita ka rin ng halimbawa kung paano gawin ito gamit ang App Router! Kung makaranas ka ng anumang problema, huwag mag-atubiling makipag-ugnayan, at ikalulugod naming tumulong.

Pinapayagan ng TacoTranslate na awtomatikong i-localize ang iyong mga aplikasyon ng React nang mabilis papunta at mula sa mahigit 75 wika. Magsimula na ngayon!