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

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

Σε αυτό το άρθρο, θα εξερευνήσουμε πώς να προσθέσετε διεθνοποίηση στην εφαρμογή σας React Next.js, με server side 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. Δημιουργήστε λογαριασμό εδώ. Είναι δωρεάν, και δεν απαιτείται να προσθέσετε πιστωτική κάρτα.

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

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

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

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

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

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

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

Για να ενσωματώσετε το TacoTranslate με την εφαρμογή σας, θα χρειαστεί να δημιουργήσετε έναν client χρησιμοποιώντας τα API keys που αναφέραμε προηγουμένως. Για παράδειγμα, δημιουργήστε ένα αρχείο με όνομα /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 σύντομα.

Η δημιουργία του client σε ξεχωριστό αρχείο το καθιστά εύκολο στη χρήση ξανά αργότερα. Το 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, το ριζικό layout στην εφαρμογή μας. Σημειώστε ότι αυτό το μονοπάτι έχει έναν φάκελο που χρησιμοποιεί 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, δημιουργήστε ή τροποποιήστε το αρχείο /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. Εάν βρισκόμαστε σε τοπικό, δοκιμαστικό ή περιβάλλον staging (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 σύμφωνα με την Τεκμηρίωση Middleware του Next.js.

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

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

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

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

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