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ştiricilerinin farklı ülkelerden ve kültürlerden gelen kullanıcılara hitap edebilen uygulamalar geliştirmesi giderek daha önemli hale geliyor. Bunu başarmanın temel yollarından biri, uygulamanızı farklı dillere, para birimlerine ve tarih formatlarına uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n)'dir.

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

Bu kılavuz, Pages Router kullanan Next.js uygulamaları içindir.
Eğer App Router kullanıyorsanız, lütfen bunun yerine bu kılavuza 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. Birçok popüler kütüphane vardır; örneğin 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ü kurduğunuza göre artık 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 olarak adlandırdığımız anahtardır; read/write anahtarı ise secret anahtarıdı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ı üretim ortamlarına kesinlikle sızdırmayın.

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 bunu İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Dizelerinizin saklanacağı “klasör”, örneğin web sitenizin URL'si. Origins 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 gerekir. Örneğin, /tacotranslate-client.js adında 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 yeniden kullanmayı kolaylaştırır. Şimdi, özel /pages/_app.tsx dosyasını 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 varsa, lütfen tanımı yukarıdaki özellikler ve kod ile genişletin.

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

TacoTranslate, çevirilerinizin sunucu tarafında render edilmesine olanak tanır. Bu, çevrilmemiş içeriğin önce kısa bir süre görünmesi yerine çevirilerin hemen gösterilmesini sağlayarak kullanıcı deneyimini önemli ölçüde iyileştirir. Ayrıca, gerekli tüm çevirilere zaten sahip olduğumuz için istemci tarafında ağ isteklerini atlayabiliriz.

/next.config.js dosyasını oluşturarak veya değiştirerek başlayacağız.

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 hale getirmek için isProduction kontrolünü değiştirin. Eğer true, 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.

Şu ana kadar Next.js uygulamasını yalnızca desteklenen dillerin bir listesiyle 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. Varsayılan olarak revalidate değerinin getTacoTranslateStaticProps içinde 60 olarak ayarlandığını unutmayın; böylece çevirileriniz güncel kalır.

Bu fonksiyonlardan herhangi birini bir sayfada kullanmak için, örneğ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 metinleri çevirmek için Translate bileşenini kullanabilmelisiniz.

import {Translate} from 'tacotranslate/react';

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

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

İşimiz bitti! React uygulamanız artık Translate bileşenine herhangi bir metin eklediğinizde otomatik olarak çevrilecektir. API anahtarında read/write izinleri bulunan ortamların yeni çevrilecek metinler oluşturabileceğini unutmayın. Üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz kapalı ve güvenli bir staging ortamı bulundurmanızı; canlıya geçmeden önce yeni metinleri ekleyerek test yapmanızı öneririz. Bu, hiç kimsenin gizli API anahtarınızı çalmasını ve yeni, alakasız metinler ekleyerek çeviri projenizi şişirme riskini önleyecektir.

GitHub profilimizdeki tam örneği mutlaka inceleyin. Orada, bu işlemin App Router kullanılarak nasıl yapılacağına dair bir örnek de bulacaksınız! Herhangi bir sorunla karşılaşırsanız, bize ulaşmaktan çekinmeyin, memnuniyetle yardımcı oluruz.

TacoTranslate, React uygulamalarınızı 75'ten fazla dile ve bu dillerden otomatik olarak, hızlı bir şekilde yerelleştirmenizi sağlar. Hemen başlayın!