Sut i weithredu rhyngwladoli mewn cais Next.js sy'n defnyddio'r App Router

Wrth i'r byd ddod yn fwy byd-eang, mae'n dod yn fwyfwy pwysig i ddatblygwyr gwe adeiladu cymwysiadau a all ddiwallu defnyddwyr o wledydd a diwylliannau gwahanol. Un o'r prif ffyrdd o gyflawni hyn yw trwy rhyngwladoli (i18n), sy'n eich galluogi i addasu eich cais i wahanol ieithoedd, arian cyfred, a fformatiau dyddiad.

Yn yr erthygl hon, byddwn yn archwilio sut i ychwanegu rhyngwladoli i'ch cais React Next.js, gyda rendro ar y gweinydd. TL;DR: Gweler yr enghraifft lawn yma.

Mae'r canllaw hwn ar gyfer cymwysiadau Next.js sy'n defnyddio'r App Router.
Os ydych chi'n defnyddio'r Pages Router, gweler y canllaw hwn yn lle hynny.

Cam 1: Gosod llyfrgell i18n

Er mwyn gweithredu rhyngwladoli yn eich cais Next.js, byddwn yn dechrau drwy ddewis llyfrgell i18n. Mae sawl llyfrgell boblogaidd, gan gynnwys next-intl. Yn yr enghraifft hon, fodd bynnag, byddwn yn defnyddio TacoTranslate.

Mae TacoTranslate yn cyfieithu eich llinynnau yn awtomatig i unrhyw iaith gan ddefnyddio deallusrwydd artiffisial arloesol, ac yn eich rhyddhau rhag y gwaith diflas o reoli ffeiliau JSON.

Gadewch i ni ei osod drwy ddefnyddio npm yn eich derfynell:

npm install tacotranslate

Cam 2: Creu cyfrif TacoTranslate am ddim

Nawr eich bod wedi gosod y modiwl, mae'n bryd creu'ch cyfrif TacoTranslate, prosiect cyfieithu, a'r allweddi API cysylltiedig. Creu cyfrif yma. Mae'n rhad ac am ddim, ac nid oes angen ichi ychwanegu cerdyn credyd.

O fewn rhyngwyneb ap TacoTranslate, creu prosiect, a mynd at ei dab allweddi API. Creu un allwedd read, a un arall read/write. Byddwn yn eu cadw fel newidynnau amgylcheddol. Y allwedd read yw'r hyn a elwir gennym yn public, a'r allwedd read/write yw'r hyn a elwir yn secret. Er enghraifft, gallech eu hychwanegu at ffeil .env yn wraidd eich prosiect.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gwnewch yn siŵr na fyddwch byth yn datgelu'r allwedd API gyfrinachol read/write i amgylcheddau cynhyrchu ar ochr y cleient.

Byddwn hefyd yn ychwanegu dau newidyn amgylcheddol arall: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Cod locale diofyn a ddefnyddir fel ateb wrth fethu. Yn yr enghraifft hon, byddwn yn ei osod i en ar gyfer Saesneg.
• TACOTRANSLATE_ORIGIN: Yr “ffolder” lle bydd eich llinynnau yn cael eu storio, megis URL eich gwefan. Darllenwch ragor am darddiadau yma.

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

Cam 3: Sefydlu TacoTranslate

I integreiddio TacoTranslate gyda’ch cais, bydd angen i chi greu cleient gan ddefnyddio’r allweddi API o’r blaen. Er enghraifft, creu ffeil o’r enw /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;

Byddwn yn diffinio TACOTRANSLATE_API_KEY a TACOTRANSLATE_PROJECT_LOCALE yn awtomatig yn fuan.

Mae creu'r cleient mewn ffeil ar wahân yn ei gwneud hi'n hawdd ei ddefnyddio eto nes ymlaen. getLocales yw swyddogaeth ddefnyddiol sy'n cynnwys trin gwallau wedi'i hadeiladu i mewn. Nawr, creu ffeil o'r enw /app/[locale]/tacotranslate.tsx, lle byddwn yn gweithredu'r darparwr TacoTranslate.

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

Sylwch ar y 'use client'; sy'n nodi bod hwn yn gydran cleient.

Gan fod y darparwr cyd-destun bellach yn barod, creu ffeil o'r enw /app/[locale]/layout.tsx, y llun gwraidd yn ein cais. Sylwch fod gan y llwybr hwn ffolder sy'n defnyddio Dynamic Routes, lle mae [locale] yn baramedr deinamig.

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

Y peth cyntaf i’w nodi yma yw ein bod yn defnyddio ein paramedr Dynamic Route [locale] i nôl cyfieithiadau ar gyfer y iaith honno. Yn ogystal, mae generateStaticParams yn sicrhau bod pob cod locale rydych wedi’u actifadu ar gyfer eich prosiect yn cael eu rhag-gynhyrchu.

Nawr, gadewch i ni adeiladu ein tudalen gyntaf! Creu ffeil o'r enw /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!" />
	);
}

Sylwch ar y newidyn revalidate sy'n dweud wrth Next.js ailadeiladu'r dudalen ar ôl 60 eiliad, a chadw eich cyfieithiadau yn gyfredol.

Cam 4: Gweithredu rendro ar y gweinydd

Mae TacoTranslate yn cefnogi rendro ochr y gweinydd. Mae hyn yn gwella profiad y defnyddiwr yn aruthrol gan ei fod yn dangos cynnwys wedi'i gyfieithu ar unwaith, yn hytrach na dangos fflach o gynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn hepgor ceisiadau rhwydwaith ar y cleient, oherwydd bod gennym eisoes y cyfieithiadau sydd eu hangen ar gyfer y dudalen y mae'r defnyddiwr yn ei gweld.

I sefydlu rendro ar ochr y gweinydd, creu neu addasu /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};
};

Addaswch y gwirio isProduction i weddu i'ch gosodiad. Os true, bydd TacoTranslate yn dangos yr allwedd API gyhoeddus. Os ydym mewn amgylchedd lleol, prawf, neu arfaethedig (isProduction is false), byddwn yn defnyddio'r allwedd API gyfrinachol read/write i sicrhau bod llinynnau newydd yn cael eu hanfon at gyfieithu.

Er mwyn sicrhau bod llwybrio a hailgyfeirio yn gweithio fel y disgwylir, bydd angen i ni greu ffeil o'r enw /middleware.ts. Gan ddefnyddio Middleware, gallwn ailgyfeirio defnyddwyr at dudalennau a gyflwynir yn eu hiaith ddewisol.

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

Sicrhewch fod y matcher wedi'i sefydlu yn unol â dogfennaeth Middleware Next.js.

Ar ochr y cleient, gallwch addasu'r cwci locale i newid pa iaith sy'n well gan y defnyddiwr. Gweler y cod enghreifftiol cyflawn am syniadau ar sut i wneud hyn!

Cam 5: Lansio a phrofi!

Rydym wedi gorffen! Bydd eich cymhwysiad React bellach yn cael ei gyfieithu'n awtomatig pan fyddwch yn ychwanegu unrhyw linynnau i gydran Translate. Sylwch mai dim ond amgylcheddau sydd â chaniatâd read/write ar yr allwedd API fydd yn gallu creu linynnau newydd i'w cyfieithu. Rydym yn argymell cael amgylchedd paratoi caeedig a diogel lle gallwch brofi eich cymhwysiad cynhyrchu gyda allwedd API o'r fath, gan ychwanegu linynnau newydd cyn mynd yn fyw. Bydd hyn yn atal unrhywun unrhywun rhag dwyn eich allwedd API gyfrinachol, ac efallai hefyd yn achosi i'ch prosiect cyfieithu dyfu'n ormodol trwy ychwanegu linynnau newydd nad ydynt yn berthnasol.

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!