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

Wrth i'r byd ddod yn fwy rhyngwladol, mae'n dod yn fwy ac yn fwy o bwys i ddatblygwyr gwe adeiladu cymwysiadau sy'n gallu gwasanaethu defnyddwyr o wledydd a diwylliannau gwahanol. Un o'r ffyrdd allweddol i gyflawni hyn yw drwy ryngwladoli (i18n), sy'n eich galluogi i addasu eich cais i wahanol ieithoedd, arian cyfred, a fformatau dyddiad.

Mewn erthygl hon, byddwn yn archwilio sut i ychwanegu ryngwladoli i'ch cais React Next.js, gyda rendro ochr 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 yn defnyddio’r Pages Router, gweler y canllaw hwn yn lle hynny.

Step 1: Gosod llyfrgell i18n

I roi rhyngwladoli i weithred 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 yn awtomatig i unrhyw iaith gan ddefnyddio AI blaengar, ac yn eich rhyddhau rhag y gwaith diflas o reoli ffeiliau JSON.

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

npm install tacotranslate

Cam 2: Creu cyfrif TacoTranslate am ddim

Now that you’ve got the module installed, it’s time to create your TacoTranslate account, a translation project, and associated API keys. Creu cyfrif yma. Mae’n rhad ac am ddim, ac nid oes angen i chi ychwanegu cerdyn credyd.

Ymhlith rhyngwyneb defnyddiwr TacoTranslate, creu prosiect, a llywio i'r tab allweddi API. Creu un allwedd read, a un allwedd read/write. Byddwn yn eu cadw fel newidynnau amgylcheddol. Y allwedd read yw'r hyn yr ydym yn ei alw yn public, a'r allwedd read/write yw secret. Er enghraifft, gallech eu hychwanegu at ffeil .env yng nghraidd eich prosiect.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gwnewch yn siŵr nad ydych byth yn dadleoli’r allwedd API gyfrinachol read/write i amgylcheddau cynhyrchu ochr y cleient.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Y cod locale diofyn i ddychwelyd ato. 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 ragor am y gwreiddiau 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 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 cyn bo hir.

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 drin gwallau adeiledig. Nawr, creu ffeil o'r enw /app/[locale]/tacotranslate.tsx, lle byddwn yn gweithredu’r ddarparwr 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 nodi bod hwn yn gydran cleient.

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 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 lleoliad rydych wedi’i actifadu ar gyfer eich prosiect yn cael eu rhag-renderio.

Nawr, gadewch i ni adeiladu ein tudalen gyntaf! Creuwch 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’n gyfredol.

Cam 4: Gweithredu rendro ochr y gweinydd

Mae TacoTranslate yn cefnogi rendro ochr y gweinydd. Mae hyn yn gwella profiad y defnyddiwr yn sylweddol trwy ddangos cynnwys wedi'i gyfieithu yn syth, yn hytrach na golau byr o gynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn sgipio ceisiadau rhwydwaith ar y cleient, oherwydd bod gennym eisoes y cyfieithiadau sydd eu hangen ar gyfer y dudalen y mae'r defnyddiwr yn ei gwylio.

I osod rendro 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 fodloni eich gosodiad. Os yw true, bydd TacoTranslate yn dangos y allwedd API cyhoeddus. Os ydym mewn amgylchedd lleol, prawf, neu gamu ymlaen (isProduction is false), byddwn yn defnyddio’r allwedd API cyfrinachol read/write i sicrhau bod cadwyni newydd yn cael eu hanfon ar gyfer cyfieithu.

I sicrhau bod llwybr a hailgyfeirio 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 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);
}

Gwnewch yn siŵr eich bod yn sefydlu’r matcher yn unol â dogfennaeth Middleware Next.js.

Ar y cleient, gallwch newid y cwci locale i newid pa iaith sydd yn ddewis gan y defnyddiwr. Gweler y cod enghreifftiol cyflawn am awgrymiadau ar sut i wneud hyn!

Cam 5: Ymgynnull a phrofi!

Rydym wedi gorffen! Bydd eich cais React yn cael ei gyfieithu’n awtomatig yn awr pan fyddwch yn ychwanegu unrhyw linynnau i gydran Translate. Nodwch mai dim ond amgylcheddau sydd ag awdurdodau read/write ar yr allwedd API fydd yn gallu creu llinynnau newydd i’w cyfieithu. Rydym yn argymell cael amgylchedd cynhyrchu wedi’i gau a diogel lle gallwch brofi’ch cais cynhyrchu gyda 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, a hefyd yn rhagweld y gallai eich prosiect cyfieithu fyw iawn trwy ychwanegu llinynnau newydd, heb fod yn gysylltiedig.

Gwnewch yn siŵr eich bod yn edrych ar y enghraifft gyflawn ar ein proffil GitHub. Yno, fe welwch hefyd enghraifft o sut i wneud hyn gan ddefnyddio'r Pages Router![Os byddwch yn wynebu unrhyw broblemau, mae croeso i chi gysylltu, a byddwn yn fwy na pharod i helpu.

Mae TacoTranslate yn caniatáu i chi leoleiddio eich ceisiadau React yn awtomatig yn gyflym i ac o unrhyw iaith. Dechreuwch heddiw!