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

Dünya daha da küreselleştikçe, web geliştiricilerin farklı ülkelerden ve kültürlerden gelen kullanıcıların ihtiyaçlarına hitap eden uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın ana yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanızı sağlayan uluslararasılaştırma (i18n) yöntemidir.

Bu makalede, React Next.js uygulamanıza sunucu tarafı render ile nasıl uluslararasılaştırma ekleyeceğimizi inceleyeceğiz. TL;DR: Tam örneği burada görün.

Bu kılavuz, App Router kullanan Next.js uygulamaları içindir.
Eğer Pages Router kullanıyorsanız, bunun yerine bu kılavuzu inceleyin.

Adım 1: Bir i18n kütüphanesi kurun

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 bulunmaktadır, bunlar arasında next-intl. Ancak bu örnekte TacoTranslate'ı kullanacağız.

TacoTranslate, son teknoloji yapay zekâ kullanarak metinlerinizi otomatik olarak herhangi bir dile çevirir ve sizi JSON dosyalarının zahmetli yönetiminden kurtarır.

Terminalinizde npm kullanarak yükleyelim:

npm install tacotranslate

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

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

TacoTranslate uygulamasının kullanıcı 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 anahtar, read/write anahtarı ise secret dediğimiz anahtardı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 adet ortam değişkeni daha ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek (fallback) yerel ayar kodu. Bu örnekte, İngilizce için bunu en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Stringlerinizin 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'ı uygulamanıza entegre etmek için, ö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, onu daha sonra tekrar kullanmayı kolaylaştırır. getLocales sadece yerleşik hata işleme içeren bir yardımcı fonksiyondur. Ş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'; öğesine dikkat edin.

Bağlam sağlayıcısı artık hazır olduğuna göre, uygulamamızın kök düzeni olan /app/[locale]/layout.tsx adlı bir dosya oluşturun. Bu yolun, Dynamic Routes kullanan bir klasöre sahip olduğunu unutmayın; 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 ilk dikkat edilmesi gereken şey, bu dil için çevirileri almak üzere parametremiz olan Dynamic Route [locale] öğesini kullanıyor olmamızdır. Ayrıca, generateStaticParams projeniz için etkinleştirdiğiniz tüm locale kodlarının önceden oluşturulmasını sağlıyor.

Ş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!" />
	);
}

Sayfanın 60 saniye sonra yeniden oluşturulmasını ve çevirilerinizin güncel kalmasını sağlayan revalidate değişkenine dikkat edin.

Adım 4: Sunucu tarafı render işleminin uygulanması

TacoTranslate sunucu tarafı render'ı destekler. Bu, çevrilmemiş içeriğin kısa bir süre görüntülenip sonra çevirinin gelmesi yerine çevrilmiş içeriğin hemen gösterilmesiyle kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, kullanıcının görüntülediği sayfa için gerekli çevirilere zaten sahip olduğumuzdan istemci tarafında ağ isteklerini atlayabiliriz.

Sunucu tarafı render'ı ayarlamak 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};
};

Yapınıza uygun olması için isProduction kontrolünü değiştirin. Eğer true ise, TacoTranslate genel API anahtarını kullanacaktır. Lokal, test veya staging ortamındaysak (isProduction is false), yeni dizelerin çeviri için gönderilmesini sağlamak amacıyla 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 adında 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 öğesini Next.js Middleware belgelerine uygun ş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 koduna bakın!

Adım 5: Yayınlayın ve test edin!

Tamamladık! React uygulamanız artık herhangi bir dizeyi Translate bileşenine eklediğinizde otomatik olarak çevrilecektir. API anahtarında read/write izinleri olan ortamların yeni çevrilecek dizeler oluşturabileceğini unutmayın. Üretim uygulamanızı bu tür bir API anahtarıyla test edebileceğiniz, yayına almadan önce yeni dizeleri ekleyebileceğiniz kapalı ve güvenli bir staging ortamı kullanmanızı öneririz. Bu sayede kimsenin gizli API anahtarınızı çalmasını ve yeni, alakasız dizeler ekleyerek çeviri projenizi potansiyel olarak şişirmesini engellemiş olursunuz.

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!