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

Wrth i'r byd ddod yn fwy byd-eang, mae'n dod yn fwyfwy pwysig i ddatblygwyr gwe adeiladu cymwysiadau sy'n gallu diwallu anghenion defnyddwyr o wledydd a diwylliannau gwahanol. Un o'r prif ffyrdd i gyflawni hyn yw trwy rhyngwladoli (i18n), sy'n caniatáu i chi addasu eich cymhwysiad i wahanol ieithoedd, arian cyfred, a fformatau dyddiad.

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

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

Cam 1: Gosod llyfrgell i18n

I weithredu rhyngwladoli yn eich cais Next.js, byddwn yn dewis llyfrgell i18n yn gyntaf. Mae sawl llyfrgell boblogaidd, gan gynnwys next-intl. Yn yr enghraifft hon, fodd bynnag, byddwn yn defnyddio TacoTranslate.

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

Gadewch i ni ei osod gan ddefnyddio npm yn eich terfynell:

npm install tacotranslate

Cam 2: Creu cyfrif TacoTranslate am ddim

Nawr eich bod wedi gosod y modiwl, mae'n amser i greu eich cyfrif TacoTranslate, prosiect cyfieithu, a allweddau API cysylltiedig. Creu cyfrif yma. Mae'n rhad ac am ddim, ac nid oes angen i chi ychwanegu cerdyn credyd.

Mewn rhyngwyneb defnyddiwr TacoTranslate, crëwch brosiect a llywiwch at y tab allweddi API iddo. Creu un read allwedd a un read/write allwedd. Byddwn yn eu cadw fel newidynnau amgylcheddol. Y allwedd read yw'r hyn a'i gelwir yn public, a'r allwedd read/write yw 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 ochr y cleient.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Y cod lleoliad diofyn a ddefnyddir fel wrth-fallback os nad oes cyfieithiad. Yn yr enghraifft hon, byddwn yn ei osod i en ar gyfer Saesneg.
• TACOTRANSLATE_ORIGIN: Y “ffolder” lle bydd eich linynnau yn cael eu storio, megis URL eich gwefan. Darllenwch fwy am darddiadau yma.

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

Cam 3: Sefydlu TacoTranslate

Er mwyn integreiddio TacoTranslate gyda’ch cais, bydd angen i chi greu cleient gan ddefnyddio’r allweddi API a sefydlwyd yn gynharach. Er enghraifft, crewch 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 defnyddio eto yn y dyfodol. getLocales yw dim ond swyddogaeth ddefnyddiol â rhywfaint o drin gwallau wedi'u hadeiladu. Nawr, creu ffeil o'r enw /app/[locale]/tacotranslate.tsx, lle byddwn ni'n 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 mai gydran ar ochr y cleient yw hon.

Gan fod y ddarparwr cyd-destun bellach yn barod, creu ffeil o'r enw /app/[locale]/layout.tsx, sef y layout gwraidd yn ein cais. Sylwch fod y llwybr hwn yn cynnwys ffolder sy'n defnyddio Dynamic Routes, lle mae [locale] yn y paramedr 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 galluogi ar gyfer eich prosiect wedi’u rhag-rendu.

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!" />
	);
}

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

Cam 4: Gweithredu rendro ar ochr y gweinydd

Mae TacoTranslate yn cefnogi rendro ar ochr y gweinydd. Mae hyn yn gwella profiad y defnyddiwr yn aruthrol drwy ddangos cynnwys wedi'i gyfieithu ar unwaith, yn hytrach na 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 mae'r defnyddiwr yn ei gweld.

I sefydlu rendro ochr y gweinydd, creu neu olygu /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 yr wirio isProduction i weddu’ch gosodiad. Os yw true, bydd TacoTranslate yn dangos yr allwedd API cyhoeddus. Os ydym mewn amgylchedd lleol, prawf, neu gyfnod gosod (isProduction is false), byddwn yn defnyddio’r allwedd API gyfrinachol read/write i sicrhau bod testunau 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. Trwy 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 eich bod yn sefydlu'r matcher yn unol â'r ddogfennaeth Middleware Next.js.

Ar y cleient, gallwch newid y cwci locale i newid pa iaith sydd gan y defnyddiwr fel ei ffefryn. Gweler y cod enghreifftiol llawn am syniadau ar sut i wneud hyn!

Cam 5: Rhowch ar waith a phrofwch!

Rydyn ni wedi gorffen! Bydd eich cais React bellach yn cael ei gyfieithu'n awtomatig pan fyddwch yn ychwanegu unrhyw llinynnau i gydran Translate. Sylwer mai dim ond amgylcheddau sydd â chaniatâd read/write ar yr allwedd API fydd yn gallu creu llinynnau newydd i'w cyfieithu. Rydym yn argymell cael amgylchedd staging caeedig ac wedi'i ddiogelu lle gallwch brofi eich cais cynhyrchu gydag allwedd API o'r fath, gan ychwanegu llinynnau newydd cyn mynd yn fyw. Bydd hyn yn atal unrhyw un rhag dwyn eich allwedd API gyfrinachol, ac yn bosibl arwain at ehangu diangen eich prosiect cyfieithu drwy ychwanegu llinynnau 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!