Πώς να υλοποιήσετε την διεθνοποίηση σε μια εφαρμογή Next.js που χρησιμοποιεί το App Router

Καθώς ο κόσμος γίνεται όλο και πιο παγκοσμιοποιημένος, είναι όλο και πιο σημαντικό για τους προγραμματιστές ιστού να δημιουργούν εφαρμογές που μπορούν να εξυπηρετούν χρήστες από διαφορετικές χώρες και κουλτούρες. Ένας από τους βασικούς τρόπους για να το επιτύχετε αυτό είναι μέσω της διεθνοποίησης (i18n), που σας επιτρέπει να προσαρμόσετε την εφαρμογή σας σε διαφορετικές γλώσσες, νομίσματα και μορφές ημερομηνίας.

Σε αυτό το άρθρο, θα εξερευνήσουμε πώς να προσθέσετε διεθνοποίηση στην εφαρμογή React Next.js σας, με rendering από την πλευρά του διακομιστή. TL;DR: Δείτε το πλήρες παράδειγμα εδώ.

Οδηγός αυτός είναι για εφαρμογές Next.js που χρησιμοποιούν το App Router.
Αν χρησιμοποιείτε το Pages Router, δείτε αντ’ αυτού αυτόν τον οδηγό.

Βήμα 1: Εγκαταστήστε μια βιβλιοθήκη i18n

Για να υλοποιήσετε διεθνοποίηση στην εφαρμογή σας Next.js, πρώτα θα επιλέξουμε μια βιβλιοθήκη i18n. Υπάρχουν αρκετές δημοφιλείς βιβλιοθήκες, συμπεριλαμβανομένης της next-intl. Σε αυτό το παράδειγμα, ωστόσο, θα χρησιμοποιήσουμε την TacoTranslate.

Η TacoTranslate μεταφράζει αυτόματα τις συμβολοσειρές σας σε οποιαδήποτε γλώσσα χρησιμοποιώντας τεχνολογία αιχμής AI, και σας απαλλάσσει από τη χρονοβόρα διαχείριση αρχείων JSON.

Ας το εγκαταστήσουμε χρησιμοποιώντας npm στο τερματικό σας:

npm install tacotranslate

Βήμα 2: Δημιουργήστε έναν δωρεάν λογαριασμό TacoTranslate

Τώρα που έχετε εγκαταστήσει το module, ήρθε η ώρα να δημιουργήσετε τον λογαριασμό σας στο TacoTranslate, ένα έργο μετάφρασης και τα αντίστοιχα API keys. Δημιουργήστε έναν λογαριασμό εδώ. Είναι δωρεάν και δεν απαιτείται να προσθέσετε κάρτα πιστωτική.

Μέσα στο περιβάλλον χρήστη της εφαρμογής TacoTranslate, δημιουργήστε ένα έργο και μεταβείτε στην καρτέλα με τα κλειδιά API του. Δημιουργήστε ένα κλειδί read και ένα κλειδί read/write. Θα τα αποθηκεύσουμε ως μεταβλητές περιβάλλοντος. Το κλειδί read είναι αυτό που ονομάζουμε public και το κλειδί read/write είναι secret. Για παράδειγμα, μπορείτε να τα προσθέσετε σε ένα αρχείο .env στη ρίζα του έργου σας.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Βεβαιωθείτε να μην διαρρεύσετε ποτέ το μυστικό κλειδί API read/write σε περιβάλλοντα παραγωγής στην πλευρά του πελάτη.

Θα προσθέσουμε επίσης δύο ακόμα μεταβλητές περιβάλλοντος: TACOTRANSLATE_DEFAULT_LOCALE και TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Ο προεπιλεγμένος κωδικός γλώσσας εφεδρείας. Σε αυτό το παράδειγμα, θα τον ορίσουμε σε en για τα Αγγλικά.
• TACOTRANSLATE_ORIGIN: Ο «φάκελος» όπου θα αποθηκεύονται οι συμβολοσειρές σας, όπως το URL της ιστοσελίδας σας. Διαβάστε περισσότερα για τις προελεύσεις εδώ.

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

Βήμα 3: Ρύθμιση του TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /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;

Θα ορίσουμε αυτόματα τις τιμές των TACOTRANSLATE_API_KEY και TACOTRANSLATE_PROJECT_LOCALE σύντομα.

Η δημιουργία του προγράμματος-πελάτη σε ξεχωριστό αρχείο διευκολύνει τη χρήση του ξανά αργότερα. getLocales είναι απλώς μια λειτουργία χρησιμότητας με κάποιο ενσωματωμένο χειρισμό σφαλμάτων. Τώρα, δημιουργήστε ένα αρχείο με το όνομα /app/[locale]/tacotranslate.tsx, όπου θα υλοποιήσουμε την υπηρεσία παροχής 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>
	);
}

Σημειώστε το 'use client'; που υποδεικνύει ότι αυτό είναι ένα συστατικό πελάτη.

Με τον πάροχο συμφραζομένων πλέον έτοιμο προς χρήση, δημιουργήστε ένα αρχείο με το όνομα /app/[locale]/layout.tsx, η βασική διάταξη στην εφαρμογή μας. Σημειώστε ότι αυτή η διαδρομή έχει έναν φάκελο που χρησιμοποιεί Dynamic Routes, όπου το [locale] είναι η δυναμική παράμετρος.

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

Το πρώτο που πρέπει να σημειωθεί εδώ είναι ότι χρησιμοποιούμε την παράμετρο Dynamic Route [locale] για να λάβουμε μεταφράσεις για αυτή τη γλώσσα. Επιπλέον, η generateStaticParams διασφαλίζει ότι όλοι οι κωδικοί τοπικών ρυθμίσεων που έχετε ενεργοποιήσει για το έργο σας έχουν προαποδοθεί.

Τώρα, ας δημιουργήσουμε την πρώτη μας σελίδα! Δημιουργήστε ένα αρχείο με το όνομα /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!" />
	);
}

Σημειώστε τη μεταβλητή revalidate που λέει στο Next.js να ξαναχτίσει τη σελίδα μετά από 60 δευτερόλεπτα και να κρατά τις μεταφράσεις σας ενημερωμένες.

Βήμα 4: Υλοποίηση απόδοσης στην πλευρά διακομιστή

Το TacoTranslate υποστηρίζει το server side rendering. Αυτό βελτιώνει δραματικά την εμπειρία χρήστη, εμφανίζοντας το μεταφρασμένο περιεχόμενο άμεσα, αντί να δείχνει πρώτα ένα σύντομο φλας με αμετάφραστο περιεχόμενο. Επιπλέον, μπορούμε να παραλείψουμε τα δίκτυα αιτήματα στην πλευρά του πελάτη, επειδή ήδη διαθέτουμε τις μεταφράσεις που χρειαζόμαστε για τη σελίδα που βλέπει ο χρήστης.

Για να ρυθμίσετε το server side rendering, δημιουργήστε ή τροποποιήστε το /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};
};

Τροποποιήστε τον έλεγχο isProduction ώστε να ταιριάζει με τη ρύθμισή σας. Εάν true, το TacoTranslate θα εμφανίσει το δημόσιο κλειδί API. Εάν βρισκόμαστε σε τοπικό, δοκιμαστικό ή σκηνικό περιβάλλον (isProduction is false), θα χρησιμοποιήσουμε το μυστικό κλειδί API read/write για να βεβαιωθούμε ότι αποστέλλονται νέες συμβολοσειρές για μετάφραση.

Για να διασφαλίσουμε ότι η δρομολόγηση και η ανακατεύθυνση λειτουργούν όπως αναμένεται, θα χρειαστεί να δημιουργήσουμε ένα αρχείο με όνομα /middleware.ts. Χρησιμοποιώντας το Middleware, μπορούμε να ανακατευθύνουμε τους χρήστες σε σελίδες που παρουσιάζονται στην προτιμώμενη γλώσσα τους.

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

Βεβαιωθείτε ότι έχετε ρυθμίσει το matcher σύμφωνα με το Documentation του Next.js Middleware.

Στον πελάτη, μπορείτε να αλλάξετε το locale cookie για να αλλάξετε την προτιμώμενη γλώσσα του χρήστη. Παρακαλώ δείτε τον πλήρη κώδικα παραδείγματος για ιδέες σχετικά με το πώς να το κάνετε αυτό!

Βήμα 5: Ανέβασε και δοκίμασε!

Έχουμε τελειώσει! Η εφαρμογή σας React θα μεταφράζεται τώρα αυτόματα όταν προσθέτετε οποιεσδήποτε συμβολοσειρές σε ένα Translate component. Σημειώστε ότι μόνο τα περιβάλλοντα με δικαιώματα read/write στο API key θα μπορούν να δημιουργούν νέες συμβολοσειρές προς μετάφραση. Συστήνουμε να έχετε ένα κλειστό και ασφαλές staging περιβάλλον όπου μπορείτε να δοκιμάσετε την παραγωγική σας εφαρμογή με ένα τέτοιο API key, προσθέτοντας νέες συμβολοσειρές πριν την ενεργοποίηση. Αυτό θα αποτρέψει οποιονδήποτε από το να κλέψει το μυστικό σας API key και ενδεχομένως να φουσκώσει το έργο μετάφρασής σας προσθέτοντας νέες, ασύνδετες συμβολοσειρές.

Βεβαιωθείτε να δείτε το πλήρες παράδειγμα στο προφίλ μας στο GitHub. Εκεί, θα βρείτε επίσης ένα παράδειγμα για το πώς να το κάνετε χρησιμοποιώντας το Pages Router ! Αν αντιμετωπίσετε οποιοδήποτε πρόβλημα, μη διστάσετε να επικοινωνήσετε μαζί μας, και θα χαρούμε πολύ να βοηθήσουμε.

Το TacoTranslate σας επιτρέπει να εντοπίζετε αυτόματα τις εφαρμογές React γρήγορα προς και από οποιαδήποτε γλώσσα. Ξεκινήστε σήμερα!