Pages 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ştiricileri için farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilecek uygulamalar geliştirmek giderek daha önemli hale geliyor. Bunu başarmanın önemli yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n) kullanmaktır.

Bu öğreticide, React Next.js uygulamanıza sunucu tarafı render ile birlikte nasıl uluslararasılaştırma ekleyeceğinizi inceleyeceğiz. TL;DR: Tam örneği buradan görebilirsiniz.

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

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 vardır; bunlar arasında next-intl yer alır. Ancak bu örnekte TacoTranslate kullanacağız.

TacoTranslate, metinlerinizi herhangi bir dile en son teknoloji yapay zeka kullanarak otomatik olarak ç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 ilgili API anahtarlarını oluşturma zamanı. Buradan bir hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulama 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 ve read/write anahtarı secret anahtardır. Örneğin, bunları projenizin kök dizinindeki bir .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ırmayın.

Ayrıca iki çevresel değişken daha ekleyeceğiz: TACOTRANSLATE_DEFAULT_LOCALE ve TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan geri dönüş (fallback) yerel 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 önce aldığınız 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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

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

İstemciyi ayrı bir dosyada oluşturmak, daha sonra tekrar kullanmayı kolaylaştırır. Şimdi, özel bir /pages/_app.tsx kullanarak, TacoTranslate sağlayıcısını ekleyeceğiz.

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

Zaten özel pageProps ve _app.tsx tanımlarınız varsa, lütfen yukarıdaki özellikler ve kod ile tanımı genişletin.

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

TacoTranslate, çevirilerinizin sunucu tarafında render edilmesine olanak tanır. Bu, çevirilmemiş içeriğin kısa süreli olarak görünmesi yerine çevirilmiş içeriğin anında gösterilmesini sağlayarak kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca istemci tarafında ağ isteklerini atlayabiliriz, çünkü ihtiyacımız olan tüm çeviriler zaten elimizde.

Başlangıç olarak /next.config.js dosyasını oluşturacak veya mevcutsa değiştireceğiz.

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

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

Şu ana kadar Next.js uygulamasını yalnızca desteklenen diller listesini kullanacak şekilde yapılandırdık. Bir sonraki adımda tüm sayfalarınız için çevirileri alacağız. Bunu yapmak için gereksinimlerinize bağlı olarak getTacoTranslateStaticProps veya getTacoTranslateServerSideProps kullanacaksınız.

Bu fonksiyonlar üç argüman alır: Bir Next.js Static Props Context nesnesi, TacoTranslate için yapılandırma ve isteğe bağlı Next.js özellikleri. revalidate değerinin getTacoTranslateStaticProps içinde varsayılan olarak 60 olduğuna dikkat edin; böylece çevirileriniz güncel kalır.

Her iki fonksiyonu da bir sayfada kullanmak için, /pages/hello-world.tsx gibi bir sayfa dosyanız olduğunu varsayalım.

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

Artık tüm React bileşenlerinizdeki dizeleri çevirmek için Translate bileşenini kullanabilmelisiniz.

import {Translate} from 'tacotranslate/react';

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

Adım 5: Dağıtın ve test edin!

İşimiz bitti! Artık React uygulamanız, herhangi bir dizeyi Translate bileşenine eklediğinizde otomatik olarak çevrilecektir. API anahtarında read/write izinleri olan ortamların yeni çevirilecek dizeler oluşturabileceğini unutmayın. Bu tür bir API anahtarıyla üretim uygulamanızı test edebileceğiniz kapalı ve güvenli bir hazırlık (staging) ortamı bulundurmanızı ve canlıya geçmeden önce yeni dizeleri burada eklemenizi öneririz. Bu, gizli API anahtarınızı herhangi birinin herhangi birinin çalmasını ve çeviri projenizin ilgisiz yeni dizeler eklenerek şişmesini önleyecektir.

Mutlaka GitHub profilimizdeki tam örneği inceleyin. Orada ayrıca App Router kullanılarak nasıl yapılacağına dair bir örnek de bulacaksınız! Eğer herhangi bir sorunla karşılaşırsanız, bize ulaşmaktan çekinmeyin; memnuniyetle yardımcı oluruz.

TacoTranslate, React uygulamalarınızı 75'ten fazla dile otomatik olarak hızla yerelleştirmenizi sağlar. Bugün başlayın!