Next.js uygulamalarında uluslararasılaşma (i18n) için en iyi çözüm

Nasıl çalışı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 edebilen uygulamalar geliştirmek giderek daha önemli hale geliyor. Bunlardan biri, uygulamanızı farklı dillere, para birimlerine ve tarih biçimlerine uyarlamanıza olanak tanıyan uluslararasılaştırma (i18n)'dır.

Bu öğreticide, React Next.js uygulamanıza sunucu tarafı oluşturma (server side rendering) ile birlikte uluslararasılaştırmayı nasıl ekleyeceğimizi 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ı (i18n) uygulamak için önce bir i18n kütüphanesi seçeceğiz. next-intl dahil olmak üzere birkaç popüler kütüphane var. Ancak bu örnekte TacoTranslate kullanacağız.

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

Bunu 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 ilişkili API anahtarlarını oluşturmanın zamanı geldi. Buradan hesap oluşturun. Ücretsizdir ve kredi kartı eklemenizi gerektirmez.

TacoTranslate uygulamasının 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 ve read/write anahtarı 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ı asla istemci tarafı üretim ortamlarına sızdırmadığınızdan emin olun.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Varsayılan yedek yerel ayar kodu. Bu örnekte İngilizce için en olarak ayarlayacağız.
• TACOTRANSLATE_ORIGIN: Metinlerinizin saklanacağı “folder” (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, ö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_DEFAULT_LOCALE ?? '',
});

module.exports = tacoTranslate;

Kısa süre içinde otomatik olarak TACOTRANSLATE_API_KEY tanımlayacağız.

İstemciyi ayrı bir dosyada oluşturmak, onu 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>
	);
}

Eğer zaten özel pageProps ve _app.tsx varsa, lütfen yukarıdaki özellikler ve kod ile tanımı 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 yanıp sönmesi yerine çevrilmiş içeriğin hemen gösterilmesi sayesinde kullanıcı deneyimini büyük ölçüde iyileştirir. Ayrıca, istemci tarafında ağ isteklerini atlayabiliriz, çünkü ihtiyaç duyduğumuz tüm çeviriler zaten elimizde.

Öncelikle /next.config.js dosyasını oluşturup 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 olacak şekilde isProduction kontrolünü değiştirin. Eğer true, TacoTranslate genel API anahtarını ortaya çıkaracaktır. 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.

Şimdiye 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 getireceğiz. Bunu yapmak için gereksinimlerinize bağlı olarak ya getTacoTranslateStaticProps ya da 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. Not: revalidate değeri getTacoTranslateStaticProps üzerinde varsayılan olarak 60’a ayarlanmıştır, böylece çevirileriniz güncel kalır.

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

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 kullanabiliyor olmalısınız.

import {Translate} from 'tacotranslate/react';

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

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

Tamamladık! Next.js uygulamanız artık herhangi bir dizeyi Translate bileşenine eklediğinizde otomatik olarak çevrilecek. API anahtarında read/write izinleri olan ortamlarda yalnızca yeni çevrilecek dizeler oluşturulabileceğini unutmayın. Üretim uygulamanızı böyle bir API anahtarıyla test edebileceğiniz, canlıya almadan önce yeni dizeleri ekleyebileceğiniz kapalı ve güvenli bir staging ortamı bulundurmanızı öneririz. Bu, gizli API anahtarınızın çalınmasını ve çeviri projenizin alakasız dizeler eklenerek gereksiz yere şişmesini ö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 App 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!