Sut i weithredu rhyngwladoli mewn cymhwysiad 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 ceisiadau sydd yn gallu gwasanaethu defnyddwyr o wahanol wledydd a diwylliannau. Un o'r ffyrdd allweddol i gyflawni hyn yw trwy rhyngwladoliad (i18n), sy'n eich galluogi i addasu eich cais i wahanol ieithoedd, arian cyfredau, a fformatau dyddiad.

Yn yr erthygl hon, byddwn yn archwilio sut i ychwanegu rhyngwladoliad at eich cais React Next.js, gyda chynhyrchu ochr y gweinydd. TL;DR: Gweler y 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, edrychwch ar y canllaw hwn yn lle hynny.

Cam 1: Gosod llyfrgell i18n

I roi cyflawniad i 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 llinynnau'n 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 creu eich cyfrif TacoTranslate, prosiect cyfieithu, a'r allweddi API cysylltiedig. Creu cyfrif yma. Mae'n rhad ac am ddim, a nid oes angen ichi ychwanegu cerdyn credyd.

O fewn UI ap TacoTranslate, creu prosiect, a llywio i'r tab allweddi API. Creu un allwedd read, a un allwedd read/write. Byddwn yn eu cadw fel amgylcheddau newidynnau. Yr allwedd read yw'r hyn yr ydym yn ei alw'n public a'r allwedd read/write yw secret. Er enghraifft, gallech eu hychwanegu at ffeil .env yng nghanol y prosiect.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Sicrhewch byth i ddal dŵr ar y gyfrinach read/write allwedd API i amgylcheddau cynhyrchu ar ochr y cleient.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Y cod lleoliad wrth gefn diofyn. Yn yr enghraifft hon, byddwn yn ei osod i en ar gyfer Saesneg.
• TACOTRANSLATE_ORIGIN: Y “ffolder” lle bydd eich llinynnau yn cael eu storio, megis URL eich gwefan. Darllenwch fwy am darddiad yma.

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

Cam 3: Gosod TacoTranslate

I integreiddio TacoTranslate gyda'ch cais, bydd angen i chi greu cleient gan ddefnyddio'r allweddi API a drafodwyd yn gynharach. 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 yn hawdd ei ddefnyddio eto yn nes ymlaen. Mae getLocales yn swyddogaeth ddefnyddiol sy’n cynnwys rhywfaint o driniaeth gwalliau adeiledig. 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 'use client'; sy'n dangos mai cydran cleient ydy hwn.

Gyda'r darparwr cyd-destun bellach yn barod i fynd, creu ffeil o'r enw /app/[locale]/layout.tsx, y cynllun gwraidd yn ein cais. Sylwch fod gan y llwybr hwn ffolder sy'n defnyddio Dynamic Routes, lle [locale] yw'r 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 sylwi arno yma yw ein bod yn defnyddio ein paramedr Dynamic Route [locale] i gael cyfieithiadau ar gyfer y iaith honno. Yn ogystal, mae generateStaticParams yn sicrhau bod pob cod lleol rydych wedi’i actifadu ar gyfer eich prosiect wedi'i rag-lenwi.

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’ch cyfieithiadau i’r fath ddiweddar.

Cam 4: Gwireddu rendro ochr y gweinydd

Mae TacoTranslate yn cefnogi rendro ochr y gweinydd. Mae hyn yn gwella profiad y defnyddiwr yn fawr drwy ddangos cynnwys wedi'i gyfieithu ar unwaith, yn hytrach na dangos eryr cynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn anwybyddu ceisiadau rhwydwaith ar y cleient, oherwydd mae gennym eisoes y cyfieithiadau sydd eu hangen arnom ar gyfer y dudalen mae'r defnyddiwr yn ei gwylio.

I osod rendro ochr y gweinydd, creu neu newid /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};
};

Addasu'r gwirio isProduction i fodloni eich gosodiad chi. Os yw true, bydd TacoTranslate yn dangos y allwedd API cyhoeddus. Os ydym mewn amgylchedd lleol, prawf, neu gyfnod cynhyrchu (isProduction is false), byddwn yn defnyddio'r allwedd API cyfrinachol read/write i sicrhau bod llinynnau newydd yn cael eu hanfon i'w cyfieithu.

I sicrhau bod llwybro a ailgyfeirio yn gweithio fel y disgwylir, bydd angen i ni greu ffeil o'r enw /middleware.ts. Gan ddefnyddio Middleware, gallwn ailgyfeirio defnyddwyr i dudalennau a gyflwynir yn eu iaith 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 gosod y matcher yn unol â ddogfennaeth Canolradd Next.js.

Ar y cleient, gallwch newid y cwci locale i newid iaith sydd o ddiddordeb i'r defnyddiwr. Gweler y cod enghreifftiol llawn am syniadau ar sut i wneud hyn!

Cam 5: Ymgynnull a phrofi!

Rydym wedi gorffen! Bydd eich cymhwysiad React yn cael ei gyfieithu yn awtomatig erbyn hyn pan ychwanegwch unrhyw linynnau i gydran Translate. Nodwch mai dim ond amgylcheddau sydd â chaniatâd read/write ar y allwedd API fydd yn gallu creu linynnau newydd i'w cyfieithu. Argymhellwn gael amgylchedd camu ymlaen caeedig a diogel lle gallwch brofi eich cymhwysiad cynhyrchu gyda allwedd API fel honno, gan ychwanegu linynnau newydd cyn mynd yn fyw. Bydd hyn yn atal unrhyw un rhag dwyn eich allwedd API gyfrinachol, ac yn bosibl yn atal eich prosiect cyfieithu rhag cael ei ragfanteisio drwy ychwanegu linynnau newydd nad ydynt yn gysylltiedig.

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!