Next.js 16 web sitenizi (sayfa yolunda [locale] olmadan) Intlayer kullanarak çevirin | Uluslararasılaştırma (i18n)

GitHub'da Uygulama Şablonu sayfasına bakın.

İçindekiler

Neden alternatifler yerine Intlayer?

'Next-intl' veya 'i18next' gibi ana çözümlerle karşılaştırıldığında Intlayer, aşağıdaki gibi entegre optimizasyonlarla gelen bir çözümdür:

Next.js Uygulamasında Intlayer Kurulumuna Adım Adım Rehber

1. 1

   Bağımlılıkları Yükleyin

   Gerekli paketleri npm kullanarak yükleyin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install intlayer next-intlayernpx intlayer init

   • intlayer

     Yapılandırma yönetimi, çeviri, içerik bildirimi, transpilation ve CLI komutları için uluslararasılaştırma araçlarını sağlayan çekirdek paket.

   • next-intlayer

   Intlayer'ı Next.js ile entegre eden paket. Next.js için uluslararasılaştırma amacıyla context provider'ları ve hook'lar sağlar. Ayrıca Intlayer'ı Webpack veya Turbopack ile entegre etmek için Next.js eklentisini ve kullanıcının tercih ettiği dili algılamak, çerezleri yönetmek ve URL yönlendirmesini gerçekleştirmek için bir proxy içerir.

2. 2

   Projenizi Yapılandırın

   İşte oluşturacağımız son yapı:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   .├── src│   ├── app│   │   ├── layout.tsx│   │   ├── page.content.ts│   │   └── page.tsx│   ├── components│   │   ├── clientComponentExample│   │   │   ├── client-component-example.content.ts│   │   │   └── ClientComponentExample.tsx│   │   ├── localeSwitcher│   │   │   ├── localeSwitcher.content.ts│   │   │   └── LocaleSwitcher.tsx│   │   └── serverComponentExample│   │       ├── server-component-example.content.ts│   │       └── ServerComponentExample.tsx│   └── proxy.ts├── intlayer.config.ts├── next.config.ts├── package.json└── tsconfig.json

   Eğer locale yönlendirmesi istemiyorsanız, intlayer basit bir provider / hook olarak kullanılabilir. Daha fazla ayrıntı için bu rehbere bakın.

   Uygulamanızın dillerini yapılandırmak için bir config dosyası oluşturun:

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Locales, type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         // Diğer yereller (locales)
       ],
       defaultLocale: Locales.ENGLISH,
     },
     routing: {
       mode: "search-params", // veya `no-prefix` - middleware tespiti için kullanışlı
     },
   };
   
   export default config;

   Bu yapılandırma dosyası aracılığıyla, yerelleştirilmiş URL'leri, proxy yönlendirmesini, çerez adlarını, içerik bildirimlerinizin konumunu ve uzantısını, Intlayer günlüklerini konsolda devre dışı bırakmayı ve daha fazlasını ayarlayabilirsiniz. Kullanılabilir tüm parametrelerin eksiksiz listesi için yapılandırma belgelerine bakın.

3. 3

   Intlayer'ı Next.js Yapılandırmanıza Entegre Edin

   Next.js kurulumunuzu Intlayer kullanacak şekilde yapılandırın:

   next.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { NextConfig } from "next";
   import { withIntlayer } from "next-intlayer/server";
   
   const nextConfig: NextConfig = {
     /* yapılandırma seçenekleri burada */
   };
   
   export default withIntlayer(nextConfig);

   withIntlayer() Next.js eklentisi, Intlayer'ı Next.js ile entegre etmek için kullanılır. İçerik bildirim (content declaration) dosyalarının oluşturulmasını sağlar ve geliştirme modunda bunları izler. Webpack veya Turbopack ortamlarında Intlayer ortam değişkenlerini tanımlar. Ayrıca performansı optimize etmek için alias'lar sağlar ve sunucu bileşenleriyle uyumluluğu garanti eder.

   withIntlayer() fonksiyonu bir promise fonksiyonudur. Derleme başlamadan önce intlayer sözlüklerini hazırlamanıza olanak tanır. Diğer eklentilerle birlikte kullanmak istiyorsanız, onu await edebilirsiniz. Örnek:

   ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   const nextConfig = await withIntlayer(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

   Eğer senkron olarak kullanmak isterseniz, withIntlayerSync() fonksiyonunu kullanabilirsiniz. Örnek:

   ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   const nextConfig = withIntlayerSync(nextConfig);const nextConfigWithOtherPlugins = withOtherPlugins(nextConfig);export default nextConfigWithOtherPlugins;

   Intlayer, proje komut satırı bayrakları --webpack, --turbo veya --turbopack ile ve mevcut Next.js sürümünüze göre projenizin webpack mi yoksa Turbopack mi kullandığını otomatik olarak algılar.

   next>=16 olduğunda, eğer Rspack kullanıyorsanız, Turbopack'i devre dışı bırakarak Intlayer'ın webpack yapılandırmasını kullanmasını açıkça zorlamalısınız:

   ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   withRspack(withIntlayer(nextConfig, { enableTurbopack: false }));

4. 4

   Dinamik Locale Rotalarını Tanımlayın

   RootLayout içindeki her şeyi kaldırın ve aşağıdaki kodla değiştirin:

   src/app/layout.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { Metadata } from "next";
   import type { ReactNode } from "react";
   import "./globals.css";
   import { IntlayerClientProvider, LocalPromiseParams } from "next-intlayer";
   import { getHTMLTextDir, getIntlayer } from "intlayer";
   import { getLocale } from "next-intlayer/server";
   export { generateStaticParams } from "next-intlayer";
   
   export const generateMetadata = async (): Promise<Metadata> => {
     const locale = await getLocale();
     const { title, description, keywords } = getIntlayer("metadata", locale);
   
     return {
       title,
       description,
       keywords,
     };
   };
   
   const RootLayout = async ({
     children,
   }: Readonly<{
     children: ReactNode;
   }>) => {
     const locale = await getLocale();
   
     return (
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <IntlayerClientProvider defaultLocale={locale}>
           <body>{children}</body>
         </IntlayerClientProvider>
       </html>
     );
   };
   
   export default RootLayout;

5. 5

   İçeriğinizi Deklare Edin

   Çevirileri saklamak için içerik deklarasyonlarınızı oluşturun ve yönetin:

   src/app/metadata.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t, type Dictionary } from "intlayer";
   import { Metadata } from "next";
   
   const metadataContent = {
     key: "metadata",
     content: {
       title: t({
         tr: "Projemin Başlığı",
         en: "My Project Title",
         fr: "Le Titre de mon Projet",
         es: "El Título de mi Proyecto",
       }),
   
       description: t({
         tr: "İş akışınızı sadeleştirmek ve verimliliği artırmak için tasarlanmış yenilikçi platformumuzu keşfedin.",
         en: "Discover our innovative platform designed to streamline your workflow and boost productivity.",
         fr: "Découvrez notre plateforme innovante conçue pour simplifier votre flux de travail et booster votre productivité.",
         es: "Descubra nuestra plataforma innovadora diseñada para simplificar su flujo de trabajo y aumentar su productividad.",
       }),
   
       keywords: t({
         tr: ["yenilik", "verimlilik", "iş akışı", "SaaS"],
         en: ["innovation", "productivity", "workflow", "SaaS"],
         tr: ["yenilik", "verimlilik", "iş akışı", "SaaS"],
         fr: ["innovation", "productivité", "flux de travail", "SaaS"],
         es: ["innovación", "productividad", "flujo de trabajo", "SaaS"],
       }),
     },
   } as Dictionary<Metadata>;
   
   export default metadataContent;

   src/app/page.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t, type Dictionary } from "intlayer";
   
   const pageContent = {
     key: "page",
     content: {
       getStarted: {
         main: t({
           tr: "Düzenleyerek başlayın",
           en: "Get started by editing",
           fr: "Commencez par éditer",
           es: "Comience por editar",
         }),
         pageLink: "src/app/page.tsx",
       },
     },
   } satisfies Dictionary;
   
   export default pageContent;

   İçerik deklarasyonlarınız, contentDir dizinine (varsayılan olarak ./src) dahil edildikleri sürece uygulamanızda herhangi bir yerde tanımlanabilir. Ve içerik deklarasyon dosya uzantısıyla eşleşmelidir (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

   Daha fazla ayrıntı için içerik deklarasyonu dokümantasyonuna bakın.

6. 6

   İçeriği Kodunuzda Kullanın

   Uygulamanız genelinde içerik sözlüklerinize erişin:

   src/app/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { FC } from "react";
   import { ClientComponentExample } from "@components/clientComponentExample/ClientComponentExample";
   import { ServerComponentExample } from "@components/serverComponentExample/ServerComponentExample";
   import {
     IntlayerServerProvider,
     useIntlayer,
     getLocale,
   } from "next-intlayer/server";
   import { NextPage } from "next";
   import { headers, cookies } from "next/headers";
   
   const PageContent: FC = () => {
     const content = useIntlayer("page");
   
     return (
       <>
         <p>{content.getStarted.main}</p>
         <code>{content.getStarted.pageLink}</code>
       </>
     );
   };
   
   const Page: NextPage = async () => {
     const locale = await getLocale();
   
     return (
       <IntlayerServerProvider locale={locale}>
         <PageContent />
         <ServerComponentExample />
         <ClientComponentExample />
       </IntlayerServerProvider>
     );
   };
   
   export default Page;

   • IntlayerClientProvider istemci tarafı bileşenlerine locale sağlamak için kullanılır. Layout dahil herhangi bir üst bileşene yerleştirilebilir. Ancak, Next.js'in layout kodunu sayfalar arasında paylaştığı ve bu nedenle daha verimli olduğu için bir layout içine yerleştirilmesi önerilir. IntlayerClientProvider'ı layout'ta kullanarak, her sayfa için yeniden oluşturulmasını önleyerek performansı artırır ve uygulamanız boyunca tutarlı bir yerelleştirme bağlamı sağlar.

   • IntlayerServerProvider sunucu çocuklarına locale sağlamak için kullanılır. Layout içinde ayarlanamaz.

     Layout ve page ortak bir server context paylaşamaz çünkü server context sistemi her isteğe özel bir veri deposuna (React'in cache mekanizması aracılığıyla) dayanır, bu da uygulamanın farklı segmentleri için her "context"in yeniden oluşturulmasına neden olur. Sağlayıcıyı paylaşılan bir layout'a yerleştirmek bu izolasyonu bozacak ve server bileşenlerinize server context değerlerinin doğru şekilde iletilmesini engelleyecektir.

   src/components/clientComponentExample/ClientComponentExample.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   "use client";
   
   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer";
   
   export const ClientComponentExample: FC = () => {
     const content = useIntlayer("client-component-example"); // İlgili içerik tanımını oluştur
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   src/components/serverComponentExample/ServerComponentExample.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import type { FC } from "react";
   import { useIntlayer } from "next-intlayer/server";
   
   export const ServerComponentExample: FC = () => {
     const content = useIntlayer("server-component-example"); // İlgili içerik bildirimi oluştur
   
     return (
       <div>
         <h2>{content.title}</h2>
         <p>{content.content}</p>
       </div>
     );
   };

   İçeriğinizi bir string özniteliğinde kullanmak istiyorsanız; ör. alt, title, href, aria-label vb., fonksiyonun değerini çağırmalısınız, örneğin:

   html

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   <img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

   useIntlayer hook'u hakkında daha fazla bilgi edinmek için belgelere bakın.

7. 7

   Locale Algılama için Proxy'yu Yapılandırma

   İsteğe bağlı

   Kullanıcının tercih ettiği locale'i algılamak için proxy'yu yapılandırın:

   src/proxy.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   export { intlayerProxy as proxy } from "next-intlayer/proxy";
   
   export const config = {
     matcher:
       "/((?!api|static|assets|robots|sitemap|sw|service-worker|manifest|.*\\..*|_next).*)",
   };

   intlayerProxy, kullanıcının tercih ettiği yerel dili algılamak ve onları yapılandırmada belirtildiği gibi uygun URL'ye yönlendirmek için kullanılır. Ayrıca, kullanıcının tercih ettiği yerel dili bir çerezde kaydetmeyi sağlar.

   Birden fazla proxy'yi birbirine zincirlemeniz gerekiyorsa (örneğin, kimlik doğrulama veya özel proxy'lerle intlayerProxy), Intlayer artık multipleProxies adlı bir yardımcı sağlar.

   ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { multipleProxies, intlayerProxy } from "next-intlayer/proxy";import { customProxy } from "@utils/customProxy";export const proxy = multipleProxies([intlayerProxy, customProxy]);

8. 8

   İçeriğinizin dilini değiştirin

   İsteğe bağlı

   Next.js'te içeriğinizin dilini değiştirmek için önerilen yol, kullanıcıları uygun yerelleştirilmiş sayfaya yönlendirmek amacıyla Link bileşenini kullanmaktır. Link bileşeni sayfanın önceden getirilmesini (prefetching) sağlar; bu da tam sayfa yeniden yüklemesini önlemeye yardımcı olur.

   src/components/localeSwitcher/LocaleSwitcher.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   "use client";
   
   import type { FC } from "react";
   import { Locales, getHTMLTextDir, getLocaleName } from "intlayer";
   import { useLocale } from "next-intlayer";
   
   export const LocaleSwitcher: FC = () => {
     const { locale, availableLocales, setLocale } = useLocale();
   
     return (
       <div>
         <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
         <div id="localePopover" popover="auto">
           {availableLocales.map((localeItem) => (
             <button
               key={localeItem}
               aria-current={locale === localeItem ? "page" : undefined}
               onClick={() => setLocale(localeItem)}
             >
               <span>
                 {/* Yerel (Locale) - örn. FR */}
                 {localeItem}
               </span>
               <span>
                 {/* Dil kendi yerelinde - örn. Français */}
                 {getLocaleName(localeItem, locale)}
               </span>
               <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
                 {/* Dil mevcut locale'de - örn. mevcut locale Locales.SPANISH ise "Francés" */}
                 {getLocaleName(localeItem)}
               </span>
               <span dir="ltr" lang={Locales.ENGLISH}>
                 {/* İngilizce dil adı - örn. French */}
                 {getLocaleName(localeItem, Locales.ENGLISH)}
               </span>
             </button>
           ))}
         </div>
       </div>
     );
   };

   Alternatif bir yol, useLocale hook'unun sağladığı setLocale fonksiyonunu kullanmaktır. Bu fonksiyon sayfanın prefetching yapılmasına izin vermez. Daha fazla bilgi için useLocale hook dokümantasyonuna bakın.

   Dokümantasyon referansları:

   • useLocale hook
   • getLocaleName hook
   • getLocalizedUrl hook
   • getHTMLTextDir hook
   • hrefLang özniteliği
   • lang özniteliği
   • dir özniteliği
   • aria-current özniteliği

9. 9

   Sunucu eylemlerinde geçerli yereli (locale) alın

   İsteğe bağlı

   Eğer bir sunucu eylemi içinde aktif yerel ayara (örn. e-postaları yerelleştirmek veya yerel duyarlı mantık çalıştırmak için) ihtiyacınız varsa, next-intlayer/server içinden getLocale'i çağırın:

   src/app/actions/getLocale.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   "use server";import { getLocale } from "next-intlayer/server";export const myServerAction = async () => {  const locale = await getLocale();  // locale ile bir şeyler yap};

   getLocale fonksiyonu kullanıcının yerel ayarını belirlemek için kademeli bir strateji izler:

   1. Öncelikle, proksi tarafından ayarlanmış olabilecek bir locale değerini kontrol etmek için istek başlıklarını (request headers) kontrol eder
   2. Başlıklarda locale bulunamazsa, çerezlerde (cookies) saklanan bir locale arar
   3. Çerez bulunamazsa, kullanıcının tarayıcı ayarlarından tercih edilen dili tespit etmeye çalışır
   4. Son çare olarak uygulamanın yapılandırılmış varsayılan locale değerine döner

   Bu, kullanılabilir bağlama göre en uygun yerelin seçilmesini sağlar.

10. 10

    bundle boyutunuzu optimize edin

    İsteğe bağlı

    next-intlayer kullanıldığında, sözlükler varsayılan olarak her sayfanın bundle'ına dahil edilir. bundle boyutunu optimize etmek için Intlayer, makrolar kullanarak useIntlayer çağrılarını akıllıca değiştiren isteğe bağlı bir SWC eklentisi sağlar. Bu, sözlüklerin yalnızca bunları gerçekten kullanan sayfaların bundle'larına dahil edilmesini sağlar.

    Bu optimizasyonu etkinleştirmek için @intlayer/swc paketini yükleyin. Yüklendikten sonra next-intlayer eklentiyi otomatik olarak algılar ve kullanır:

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npm install @intlayer/swc --save-dev

    Not: Bu optimizasyon yalnızca Next.js 13 ve üzeri için kullanılabilir.

    Not: Bu paket varsayılan olarak yüklenmez çünkü SWC eklentileri Next.js üzerinde hâlâ deneysel durumdadır. İleride değişebilir.

    Not: Eğer seçeneği importMode: 'dynamic' veya importMode: 'fetch' (dictionary yapılandırmasında) olarak ayarlarsanız, bu Suspense'e dayanır; bu nedenle useIntlayer çağrılarınızı bir Suspense sınırı içine almanız gerekir. Bu, useIntlayer'ı Sayfa / Layout bileşeninizin en üst düzeyinde doğrudan kullanamayacağınız anlamına gelir.

Turbopack'ta sözlük değişikliklerini izleme

next dev komutunu kullanarak geliştirme sunucunuz olarak Turbopack'i kullandığınızda, sözlük değişiklikleri varsayılan olarak otomatik algılanmaz.

Bu sınırlama, Turbopack'in içerik dosyalarınızdaki değişiklikleri izlemek için webpack eklentilerini paralel olarak çalıştıramamasından kaynaklanır. Bunu aşmak için geliştirme sunucusunu ve Intlayer derleme izleyicisini aynı anda çalıştırmak üzere intlayer watch komutunu kullanmanız gerekir.

{  // ... Mevcut package.json yapılandırmalarınız  "scripts": {    // ... Mevcut scripts yapılandırmalarınız    "dev": "intlayer watch --with 'next dev'",  },}

Eğer next-intlayer@<=6.x.x kullanıyorsanız, Next.js 16 uygulamasının Turbopack ile doğru çalışması için --turbopack bayrağını tutmanız gerekir. Bu sınırlamadan kaçınmak için next-intlayer@>=7.x.x kullanmanızı öneririz.

TypeScript'i Yapılandırma

Intlayer, TypeScript'in avantajlarından yararlanmak ve kod tabanınızı güçlendirmek için module augmentation kullanır.

TypeScript yapılandırmanızın otomatik oluşturulmuş tipleri içerdiğinden emin olun.

{  // ... Mevcut TypeScript yapılandırmalarınız  "include": [    // ... Mevcut TypeScript yapılandırmalarınız    ".intlayer/**/*.ts", // Otomatik oluşturulan türleri dahil et  ],}

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaları yoksaymanız önerilir. Bu, bu dosyaları Git deponuza commit etmekten kaçınmanızı sağlar.

Bunu yapmak için .gitignore dosyanıza aşağıdaki satırları ekleyebilirsiniz:

# Intlayer tarafından oluşturulan dosyaları yoksay.intlayer

VS Code Uzantısı

Intlayer ile geliştirme deneyiminizi iyileştirmek için resmi Intlayer VS Code Uzantısını yükleyebilirsiniz.

VS Code Marketplace'ten Yükleyin

Bu uzantı şunları sağlar:

• Otomatik tamamlama çeviri anahtarları için.
• Eksik çeviriler için gerçek zamanlı hata tespiti.
• Satır içi önizlemeler, çevrilmiş içeriğin önizlemeleri.
• Hızlı eylemler, çevirileri kolayca oluşturup güncellemek için.

Daha fazla ayrıntı için uzantının nasıl kullanılacağına dair Intlayer VS Code Extension belgelerine bakın.

Daha İleri

Daha ileri gitmek için görsel editörü uygulayabilir veya içeriğinizi CMS kullanarak dışsallaştırabilirsiniz.