App Router kullanan bir Next.js uygulamasında uluslararasılaştırma nasıl uygulanır

Dünya küreselleştikçe, web geliştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar oluşturması giderek daha önemli hale geliyor. Bunlardan biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n)'dır.

Bu makalede, React Next.js uygulamanıza sunucu tarafı render (server side rendering) ile nasıl uluslararasılaştırma ekleyeceğimizi inceleyeceğiz. TL;DR: Tam örneği burada inceleyin.

Bu rehber, App Router kullanan Next.js uygulamaları içindir.
Eğer Pages Router kullanıyorsanız, bunun yerine bu rehbere bakın.

Adım 1: Bir i18n kütüphanesi yükleyin

Next.js uygulamanızda uluslararasılaştırmayı uygulamak için önce bir i18n kütüphanesi seçeceğiz. Birkaç popüler kütüphane var, bunların arasında next-intl. Ancak bu örnekte TacoTranslate kullanacağız.

TacoTranslate, gelişmiş yapay zeka kullanarak metinlerinizi herhangi bir dile otomatik olarak çevirir ve JSON dosyalarının zahmetli yönetiminden sizi kurtarır.

Terminalinizde npm kullanarak yükleyelim:

npm install tacotranslate

Adım 2: Ücretsiz bir TacoTranslate hesabı oluşturun

Modülü kurduğunuza göre şimdi TacoTranslate hesabınızı, bir çeviri projesini ve ilgili API anahtarlarını oluşturma zamanı. Buradan bir hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulaması arayüzünde bir proje oluşturun ve API anahtarları sekmesine gidin. Bir read anahtarı ve bir read/write anahtarı oluşturun. Bunları ortam değişkenleri olarak kaydedeceğiz. read anahtarı bizim public dediğimiz anahtardır ve read/write anahtarı secret olarak adlandırılır. Örneğin, bunları projenizin kök dizinindeki .env dosyasına ekleyebilirsiniz.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Gizli read/write API anahtarını istemci tarafındaki üretim ortamlarına asla sızdırmadığınızdan emin olun.

Ayrıca iki ortam değişkeni daha ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek yerel ayar (locale) kodu. Bu örnekte İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Metinlerinizin saklanacağı “klasör”, örneğin web sitenizin URL’si. Origin'ler hakkında daha fazla bilgi edinin.

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

Adım 3: TacoTranslate'i kurma

TacoTranslate'i uygulamanıza entegre etmek için, daha önceki API anahtarlarını kullanarak bir istemci oluşturmanız gerekecek. Örneğin, /tacotranslate-client.js adlı bir dosya oluşturun.

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;

Kısa süre içinde TACOTRANSLATE_API_KEY ve TACOTRANSLATE_PROJECT_LOCALE otomatik olarak tanımlanacak.

İstemciyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. getLocales yerleşik bazı hata işleme özelliklerine sahip bir yardımcı işlevdir. Şimdi, /app/[locale]/tacotranslate.tsx' adlı bir dosya oluşturun; burada TacoTranslate sağlayıcısını uygulayacağız.

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

Bunun bir istemci bileşeni olduğunu belirten 'use client'; ifadesine dikkat edin.

Bağlam sağlayıcısı artık hazır olduğuna göre, uygulamamızdaki kök layout olan /app/[locale]/layout.tsx adlı bir dosya oluşturun. Bu yolun Dynamic Routes kullanan bir klasör içerdiğine dikkat edin; burada [locale] dinamik parametredir.

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

Burada dikkat edilmesi gereken ilk şey, o dil için çevirileri almak üzere Dynamic Route parametresi [locale] kullanılmasıdır. Ayrıca, generateStaticParams projeniz için etkinleştirdiğiniz tüm locale kodlarının önceden oluşturulmasını sağlar.

Şimdi ilk sayfamızı oluşturalım! /app/[locale]/page.tsx adlı bir dosya oluşturun.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

60 saniye sonra sayfayı yeniden oluşturmasını ve çevirilerinizi güncel tutmasını sağlayan revalidate değişkenine dikkat edin.

Adım 4: Sunucu tarafı render'ı uygulama

TacoTranslate sunucu tarafı render'ını destekler. Bu, çevirilmiş içeriği anında göstererek önce çevrilmemiş içeriğin kısa süreli bir şekilde görünmesine (flash) neden olmak yerine kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, kullanıcının görüntülediği sayfa için ihtiyaç duyduğumuz çeviriler zaten elimizde olduğu için istemci tarafında ağ isteklerini atlayabiliriz.

Sunucu tarafı render'ı yapılandırmak için, /next.config.js dosyasını oluşturun veya değiştirin:

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

Kurulumunuza uygun olacak şekilde isProduction kontrolünü değiştirin. Eğer true ise, TacoTranslate herkese açık API anahtarını görünür kılacaktır. Yerel, test veya staging ortamındaysak (isProduction is false) yeni dizelerin çeviri için gönderildiğinden emin olmak için gizli read/write API anahtarını kullanacağız.

Yönlendirme ve yeniden yönlendirmelerin beklendiği gibi çalışmasını sağlamak için /middleware.ts adlı bir dosya oluşturmamız gerekecek. Middleware kullanarak kullanıcıları tercih ettikleri dilde sunulan sayfalara yönlendirebiliriz.

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'ı Next.js Middleware belgeleri ile uyumlu olacak şekilde ayarladığınızdan emin olun.

İstemci tarafında, kullanıcının tercih ettiği dili değiştirmek için locale çerezini değiştirebilirsiniz. Bunu nasıl yapacağınıza dair fikirler için lütfen tam örnek koda bakın!

Adım 5: Yayınla ve test et!

İşimiz bitti! React uygulamanızda bir Translate bileşenine herhangi bir dize eklediğinizde artık otomatik olarak çevrilecektir. API anahtarında read/write izinlerine sahip ortamlarda yalnızca çevrilecek yeni dizeler oluşturulabileceğini unutmayın. Canlıya almadan önce yeni dizeler ekleyebileceğiniz, üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz kapalı ve güvenli bir staging ortamı bulundurmanızı öneririz. Bu, gizli API anahtarınızı herhangi birinin herhangi birinin çalmasını engelleyecek ve yeni, alakasız dizeler ekleyerek çeviri projenizin gereksiz yere şişmesini potansiyel olarak önleyecektir.

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!