Y datrysiad gorau ar gyfer rhyngwladoli (i18n) mewn apiau Next.js

Sut mae'n gweithio

Wrth i'r byd ddod yn fwy byd-eang, mae'n dod yn fwyfwy pwysig i ddatblygwyr gwe adeiladu cymwysiadau a all ddarparu ar gyfer defnyddwyr o wahanol wledydd a diwylliannau. Un o'r ffyrdd allweddol i gyflawni hyn yw trwy rhyngwladoli (i18n), sy'n caniatáu i chi addasu eich cymhwysiad i wahanol ieithoedd, arianfeydd a fformatau dyddiad.

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

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

Cam 1: Gosodwch lyfrgell i18n

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

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

Yn rhyngwyneb defnyddiwr TacoTranslate, crewch brosiect a llywiwch i'r tab Allweddi API. Crewch un read allwedd a un read/write allwedd. Byddwn yn eu cadw fel newidynnau amgylcheddol. Y 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 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 ychwanegol: TACOTRANSLATE_DEFAULT_LOCALE a TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Y cod locale diofyn a ddefnyddir fel lleoliad wrth gefn. 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 darddiadau yma.

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

Cam 3: Sefydlu TacoTranslate

Er mwyn integreiddio TacoTranslate â'ch cais, bydd angen i chi greu cleient gan ddefnyddio'r allweddi API a'u creu 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Byddwn yn diffinio TACOTRANSLATE_API_KEY yn awtomatig yn fuan.

Mae creu'r cleient mewn ffeil ar wahân yn ei gwneud yn haws ei ddefnyddio eto yn nes ymlaen. Nawr, gan ddefnyddio /pages/_app.tsx wedi'i haddasu, byddwn yn ychwanegu'r ddarparwr TacoTranslate.

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

Os oes gennych chi eisoes pageProps a _app.tsx wedi’u haddasu, estynnwch y diffiniad gyda’r priodoleddau a’r cod uchod.

Cam 4: Gweithredu rendro ar ochr y gweinydd

Mae TacoTranslate yn caniatáu rendro ar ochr y gweinydd ar gyfer eich cyfieithiadau. Mae hyn yn gwella profiad y defnyddiwr yn fawr trwy ddangos cynnwys wedi'i gyfieithu ar unwaith, yn hytrach na fflach o gynnwys heb ei gyfieithu yn gyntaf. Yn ogystal, gallwn osgoi ceisiadau rhwydwaith ar y cleient, oherwydd bod gennym eisoes yr holl gyfieithiadau sydd eu hangen arnom.

Byddwn ni'n dechrau drwy greu neu addasu /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'),
	});
};

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

Hyd yn hyn, rydym ond wedi sefydlu'r cais Next.js gyda rhestr o ieithoedd a gefnogir. Y cam nesaf fydd caffael cyfieithiadau ar gyfer eich holl dudalennau. I wneud hynny, byddwch yn defnyddio naill ai getTacoTranslateStaticProps neu getTacoTranslateServerSideProps yn dibynnu ar eich anghenion.

Mae'r swyddogaethau hyn yn cymryd tair dadleuon: Un gwrthrych Next.js Static Props Context, cyfluniad ar gyfer TacoTranslate, a phriodweddau Next.js dewisol. Noder bod revalidate ar getTacoTranslateStaticProps wedi'i osod i 60 yn ddiofyn, fel bod eich cyfieithiadau yn aros yn gyfredol.

I ddefnyddio unrhyw un o'r swyddogaethau hyn ar dudalen, gadewch i ni ragdybio bod gennych ffeil tudalen fel /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!"/>;
}

Dylech nawr allu defnyddio'r cydran Translate i gyfieithu llinynnau mewn pob un o'ch cydrannau React.

import {Translate} from 'tacotranslate/react';

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

Cam 5: Lansio a phrofi!

Rydym wedi gorffen! Bydd eich cais Next.js bellach yn cael ei gyfieithu'n awtomatig pan fyddwch yn ychwanegu unrhyw stringiau i gydran Translate. Sylwch mai dim ond amgylcheddau sydd â chaniatâd read/write ar yr allwedd API fydd yn gallu creu stringiau newydd i'w cyfieithu. Rydym yn argymell cael amgylchedd staging caeedig a diogel lle gallwch brofi eich cais cynhyrchu gyda allwedd API o'r fath, gan ychwanegu stringiau newydd cyn mynd yn fyw. Bydd hyn yn atal unrhywun unrhywun rhag dwyn eich allwedd API gyfrinachol, ac yn bosibl achosi i'ch prosiect cyfieithu ddod yn orlawn drwy ychwanegu stringiau 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 App 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!