Intlayer ile Next.js 14 and App Router çevirin | Uluslararasılaştırma (i18n)

İç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:

Ön Koşullar

Bu kılavuzu takip etmek için aşağıdaki araçlara ihtiyacınız olacak:

</Tab>

</Tab> </Tabs>

• Node.js 18 veya üzeri
• npm, pnpm veya yarn paket yöneticisi
• Next.js 14 projesi

1. 1

   Intlayer Paketlerini Kurma

   İlk olarak, Intlayer paketlerini projenize kurun:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npx intlayer init --interactive
   

   --interactive bayrağı isteğe bağlıdır. Bir yapay zeka aracısıysanız intlayer-cli init kullanın.

   Bu komut ortamınızı algılayacak ve gerekli paketleri yükleyecektir. Örneğin:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   npm install next-intlayer intlayer --save
   

   • intlayer

   Internationalization araçlarını sağlayan core package'ı, konfigürasyon yönetimi, çeviri, içerik bildirimi, transpilation ve CLI komutları için.

   • next-intlayer

   Intlayer'ı Next.js ile entegre eden paket. Next.js uluslararasılaştırması için context providers ve hooks'ları sağlar. Ayrıca, Intlayer'ı Webpack veya Turbopack ile entegre etmek için Next.js plugin'ini, ayrıca kullanıcının tercih ettiği dili algılamak, çerezleri yönetmek ve URL yeniden yönlendirmesini işlemek için middleware'i içerir.

2. 2

   Intlayer Yapılandırma Dosyası Oluşturma

   Here is the final structure that we will make:

   bash

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   .
   ├── src
   │   ├── app
   │   │   ├── [locale]
   │   │   │   ├── layout.tsx            # Locale layout for the Intlayer provider
   │   │   │   ├── page.content.ts
   │   │   │   └── page.tsx
   │   │   └── layout.tsx                # Root layout for style and global providers
   │   ├── components
   │   │   ├── client-component-example.content.ts
   │   │   ├── ClientComponentExample.tsx
   │   │   ├── LocaleSwitcher
   │   │   │   ├── localeSwitcher.content.ts
   │   │   │   └── LocaleSwitcher.tsx
   │   │   ├── server-component-example.content.ts
   │   │   └── ServerComponentExample.tsx
   │   └── middleware.ts
   ├── intlayer.config.ts
   ├── next.config.ts
   ├── package.json
   └── tsconfig.json
   

   If you don't want locale routing, intlayer can be used as a simple provider / hook. See this guide for more details.

   Proje kök dizininizde intlayer.config.ts dosyasını oluşturun:

   intlayer.config.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { Locales } from "intlayer";
   import { type IntlayerConfig } from "intlayer";
   
   const config: IntlayerConfig = {
     internationalization: {
       locales: [
         Locales.ENGLISH,
         Locales.FRENCH,
         Locales.SPANISH,
         Locales.TURKISH,
       ],
       defaultLocale: Locales.ENGLISH,
     },
     content: {
       // İçerik dosyalarınızın bulunduğu dizin
       fileExtensions: [".content.ts", ".content.js", ".content.json"],
       baseDir: "./src",
       contentDirName: "content",
       // İçerik dosyalarınızın türlerini belirtin
       types: {
         filePath: "./types/intlayer.d.ts",
         moduleAugmentation: true,
       },
     },
   };
   
   export default config;
   

   Bu yapılandırma dosyası aracılığıyla, yerelleştirilmiş URL'ler, middleware yönlendirmesi, cookie adları, içerik bildirimlerinizin konumu ve uzantısı, Intlayer günlüklerini konsolda devre dışı bırakma ve daha fazlasını ayarlayabilirsiniz. Mevcut parametrelerin tam listesi için yapılandırma belgelerine başvurun.

3. 3

   Next.js Yapılandırmasını Güncelleme

   Next.js yapılandırma dosyanızı Intlayer ile uyumlu hale getirin:

4. 4

   İçerik Bildirimi

   İçerik dosyalarınızı oluşturun. Bu dosyalar, uygulamanızdaki çok dilli içeriği tanımlar.

   src/content/home.content.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { t } from "intlayer";
   import { type ILocaleContent } from "intlayer";
   
   const homeContent = {
     title: t({
       en: "Welcome to My App",
       fr: "Bienvenue dans mon application",
       es: "Bienvenido a mi aplicación",
       tr: "Uygulamama Hoş Geldiniz",
     }),
     description: t({
       en: "This is a sample Next.js application with Intlayer",
       fr: "Ceci est un exemple d'application Next.js avec Intlayer",
       es: "Esta es una aplicación de ejemplo de Next.js con Intlayer",
       tr: "Bu, Intlayer ile örnek bir Next.js uygulamasıdır",
     }),
   } satisfies ILocaleContent;
   
   export default homeContent;
   

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

   Intlayer v9'dan bu yana, bu middleware routing.enableProxy seçeneğini respects eder (true varsayılan olarak). Bunu pass-through haline dönüştürmek için konfigürasyonunuzda routing.enableProxy: false ayarlayın ve bu dosyayı silmeyin. v9 release notes dosyasına bakın.

   Uygulamanızın rotalarıyla eşleşmesi için matcher parametresini uyarlayın. Daha fazla ayrıntı için Next.js matcher yapılandırması belgesine bakın.

   Birden fazla middleware'i bir araya getirmeniz gerekiyorsa (örneğin, intlayerMiddleware'i kimlik doğrulama veya özel middleware'lerle), Intlayer artık multipleMiddlewares adında bir yardımcı sağlıyor.

   src/content/home.content.json

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   {
     "title": {
       "en": "Welcome to My App",
       "fr": "Bienvenue dans mon application",
       "es": "Bienvenido a mi aplicación",
       "tr": "Uygulamama Hoş Geldiniz"
     },
     "description": {
       "en": "This is a sample Next.js application with Intlayer",
       "fr": "Ceci est un exemple d'application Next.js avec Intlayer",
       "es": "Esta es una aplicación de ejemplo de Next.js con Intlayer",
       "tr": "Bu, Intlayer ile örnek bir Next.js uygulamasıdır"
     }
   }
   

5. 5

   İçerik Kullanımı

   İçeriğinizi bileşenlerinizde kullanın:

   src/app/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { useIntlayer } from "next-intlayer";
   import { Locales } from "intlayer";
   
   export default function HomePage() {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }
   

   RootLayout bileşenini boş tutmak, lang ve dir özniteliklerini <html> etiketine ayarlamaya izin verir.

6. 6

   Middleware Kurulumu

   src/app/[locale]/layout.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { type Next14LayoutIntlayer } from "next-intlayer";
   import { IntlayerProvider } from "next-intlayer/server";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => (
     <IntlayerProvider locale={locale}>
       <html lang={locale} dir={getHTMLTextDir(locale)}>
         <body className={inter.className}>{children}</body>
       </html>
     </IntlayerProvider>
   );
   
   export default LocaleLayout;
   

   Tek bir IntlayerProvider, ağacın her iki yarısını da kapsar: istek kapsamlı sunucu bağlamını tohumlandırır (sunucu hooks'ları tarafından okunur) ve istemci sağlayıcısını monte eder, böylece istemci bileşenleri aynı yerel ayarı alır.

   Next.js 14'te çok dilli yönlendirme için middleware kurun:

   src/app/[locale]/layout.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { type Next14LayoutIntlayer, IntlayerProvider } from "next-intlayer";
   import { Inter } from "next/font/google";
   import { getHTMLTextDir } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   const LocaleLayout: Next14LayoutIntlayer = ({
     children,
     params: { locale },
   }) => (
     <html lang={locale} dir={getHTMLTextDir(locale)}>
       <body className={inter.className}>
         <IntlayerProvider locale={locale}>{children}</IntlayerProvider>
       </body>
     </html>
   );
   
   export default LocaleLayout;
   

   </Tab> </Tabs>

   [locale] yol segmenti, dili tanımlamak için kullanılır. Örneğin: /en-US/about en-US dilini ve /fr/about ise fr dilini ifade eder.

   Bu aşamada şu hatayı alacaksınız: Error: Missing <html> and <body> tags in the root layout.. Bu beklenen bir durumdur çünkü /app/page.tsx dosyası artık kullanılmamaktadır ve kaldırılabilir. Bunun yerine, [locale] path segment /app/[locale]/page.tsx sayfasını etkinleştirecektir. Sonuç olarak, sayfalar tarayıcınızda /en, /fr, /es gibi yollar aracılığıyla erişilebilir olacaktır. Varsayılan locale'i kök sayfa olarak ayarlamak için, 4. adımdaki middleware kurulumuna başvurun.

   Ardından, uygulamanızın Layout'unda generateStaticParams fonksiyonunu uygulayın.

   src/middleware.ts

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { createMiddleware } from "next-intlayer/middleware";
   import { type NextRequest } from "next/server";
   
   export default createMiddleware({
     // Alternatif olarak, middleware seçeneklerini özelleştirebilirsiniz
     // locales: ['en', 'fr', 'es'],
     // defaultLocale: 'en',
   });
   
   export const config = {
     matcher: ["/((?!api|_next|_vercel|.*\\..*).*)"],
   };
   

   generateStaticParams, uygulamanızın tüm locales için gerekli sayfaları önceden oluşturmasını sağlayarak runtime hesaplamasını azaltır ve kullanıcı deneyimini iyileştirir. Daha fazla bilgi için Next.js generateStaticParams belgesine bakın.

7. 7

   Düzen Dosyası (Layout)

   Kök düzen dosyanızı çok dilli hale getirin:

   src/app/layout.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import {} from "next-intlayer";
   import { getHTMLTextDir } from "intlayer";
   import { getLocaleName } from "intlayer";
   import { Inter } from "next/font/google";
   import { type Metadata } from "next/types";
   import { getIntlayer } from "next-intlayer/server";
   import { type Locales } from "intlayer";
   
   const inter = Inter({ subsets: ["latin"] });
   
   export const generateMetadata = (params: {
     params: { locale: Locales };
   }): Metadata => {
     const { locale } = params.params;
     const t = getIntlayer(locale);
   
     return {
       title: t({
         en: "My App",
         fr: "Mon Application",
         es: "Mi Aplicación",
         tr: "Uygulamam",
       }),
       description: t({
         en: "This is my Next.js app with Intlayer",
         fr: "Ceci est mon application Next.js avec Intlayer",
         es: "Esta es mi aplicación Next.js con Intlayer",
         tr: "Bu, Intlayer ile Next.js uygulamamdır",
       }),
     };
   };
   
   export default function RootLayout({
     children,
     params,
   }: {
     children: React.ReactNode;
     params: { locale: Locales };
   }) {
     const { locale } = params;
     const localeName = getLocaleName(locale);
     const textDirection = getHTMLTextDir(locale);
   
     return (
       <html lang={locale} dir={textDirection}>
         <body className={inter.className}>
           <header>
             <h1>{localeName}</h1>
           </header>
           {children}
         </body>
       </html>
     );
   }
   

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

   Daha fazla bilgi için içerik bildirimi belgelerine başvurun.

8. 8

   Sayfa Yönlendirme

   Sayfa yönlendirmelerini çok dilli hale getirin:

   src/app/[locale]/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { useIntlayer } from "next-intlayer";
   import { Locales } from "intlayer";
   
   export default function HomePage() {
     const content = useIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }
   

   • IntlayerProvider yerel düzen içinde bir kez monte edilir. Sunucu ve istemci bileşenlerine yerel ayarları sağlar, bu nedenle sayfalar artık kendilerini sarmalamaz.
   • Sunucu hooks'ları yerel ayarları şu sırayla çözer: çağrı sitesinde geçirilen yerel ayar, ardından sağlayıcı tarafından başlatılan sunucu bağlamı, ardından istekle taşınan yerel ayar (Intlayer proxy'si tarafından ayarlanan x-intlayer-locale başlığı, ardından yerel ayar cookie'si). Bu son adım, yalnızca sayfa segmentini yeniden işleyen istemci tarafı navigasyonunda içeriğin doğru kalmasını sağlar; burada düzen — ve onunla birlikte sağlayıcı — yeniden çalışmaz.

   src/app/[locale]/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { ClientComponentExample } from "@components/ClientComponentExample";
   import { ServerComponentExample } from "@components/ServerComponentExample";
   import { type Next14PageIntlayer } from "next-intlayer";
   import { IntlayerServerProvider, useIntlayer } from "next-intlayer/server";
   
   const Page: Next14PageIntlayer = ({ params: { locale } }) => {
     const content = useIntlayer("page", locale);
   
     return (
       <>
         <p>
           {content.getStarted.main}
           <code>{content.getStarted.pageLink}</code>
         </p>
   
         <IntlayerServerProvider locale={locale}>
           <ServerComponentExample />
           <ClientComponentExample />
         </IntlayerServerProvider>
       </>
     );
   };
   
   export default Page;
   

   • IntlayerClientProvider istemci tarafı bileşenlerine locale sağlamak için kullanılır. Herhangi bir ana bileşene, düzen (layout) dahil olmak üzere yerleştirilebilir. Ancak, düzene yerleştirmek önerilir çünkü Next.js düzen kodunu sayfalar arasında paylaştığı için daha verimlidir. Düzende IntlayerClientProvider kullanarak, her sayfa için yeniden başlatmaktan kaçınır, performansı iyileştirir ve uygulamanız genelinde tutarlı bir lokalizasyon bağlamı sağlarsınız.
   • IntlayerServerProvider sunucu alt öğelerine locale sağlamak için kullanılır. Düzende ayarlanamaz.

   Layout ve page ortak bir server context paylaşamaz çünkü server context sistemi, per-request data store'a dayalıdır (React's cache mekanizması aracılığıyla), bu da her "context"in uygulamanın farklı segmentleri için yeniden oluşturulmasına neden olur. Provider'ı shared layout'a yerleştirmek bu izolasyonu bozar, server context değerlerinin server component'lerinize doğru şekilde yayılmasını engeller.

src/components/ClientComponentExample.tsx

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

"use client";

import type { FC } from "react";
import { useIntlayer } from "next-intlayer";

const ClientComponentExample: FC = () => {
  const content = useIntlayer("client-component-example"); // İlgili içerik bildirimini oluştur

  return (
    <div>
      <h2>{content.title}</h2>
      <p>{content.content}</p>
    </div>
  );
};

9. 9

   Meta Verilerin Uluslararasılaştırılması

   src/components/ServerComponentExample.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

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

   next-intlayer isomorphic import yoludur: react-server export koşulu sunucu bileşenlerine ambient-locale uygulamasını verirken, istemci bileşenleri context-backed olanı alır. Aynı çağrı her iki tarafta da çalışır.

   Sayfa meta verilerini uluslararasılaştırın:

   src/app/[locale]/page.tsx

   İçeriği kopyala

   Kodu kopyala

   Kodu panoya kopyala

   import { getIntlayer } from "next-intlayer/server";
   import { type Locales } from "intlayer";
   import { type Metadata } from "next/types";
   
   export const generateMetadata = (params: {
     params: { locale: Locales };
   }): Metadata => {
     const { locale } = params.params;
     const t = getIntlayer(locale);
   
     return {
       title: t({
         en: "Home Page",
         fr: "Page d'accueil",
         es: "Página de inicio",
         tr: "Ana Sayfa",
       }),
       description: t({
         en: "Welcome to the home page",
         fr: "Bienvenue sur la page d'accueil",
         es: "Bienvenido a la página de inicio",
         tr: "Ana sayfaya hoş geldiniz",
       }),
     };
   };
   
   export default function HomePage() {
     const content = getIntlayer("home");
   
     return (
       <div>
         <h1>{content.title}</h1>
         <p>{content.description}</p>
       </div>
     );
   }
   

   </Tab> </Tabs>

   İçeriğinizi alt, title, href, aria-label gibi bir string özniteliğinde kullanmak istiyorsanız, fonksiyonun değerini şu şekilde kullanabilirsiniz:

   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 hakkında daha fazla bilgi için belgelere bakınız.

10. 10

    Site Haritası ve Robots.txt Kurulumu

    Site haritanızı ve robots.txt dosyanızı çok dilli hale getirin:

    src/app/[locale]/sitemap.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    import { type MetadataRoute } from "next";
    
    export default function sitemap(): MetadataRoute.Sitemap {
      const locales = [
        Locales.ENGLISH,
        Locales.FRENCH,
        Locales.SPANISH,
        Locales.TURKISH,
      ];
    
      return [
        {
          url: getLocalizedUrl("/", Locales.ENGLISH),
          lastModified: new Date(),
          changeFrequency: "yearly",
          priority: 1,
          alternates: {
            languages: locales.reduce(
              (acc, locale) => ({
                ...acc,
                [locale]: getLocalizedUrl("/", locale),
              }),
              {}
            ),
          },
        },
      ];
    }
    

    src/app/[locale]/robots.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    import { type MetadataRoute } from "next";
    
    export default function robots(): MetadataRoute.Robots {
      return {
        rules: {
          userAgent: "*",
          allow: "/",
          disallow: "/private/",
        },
        sitemap: getLocalizedUrl("/sitemap.xml", Locales.ENGLISH),
      };
    }
    

    src/app/[locale]/layout.tsx or src/app/[locale]/page.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getIntlayer, getMultilingualUrls } from "intlayer";
    import type { Metadata } from "next";
    import type { LocalParams } from "next-intlayer";
    
    export const generateMetadata = ({
      params: { locale },
    }: LocalParams): Metadata => {
      const metadata = getIntlayer("page-metadata", locale);
    
      /**
       * Her locale için tüm url'leri içeren bir nesne oluşturur.
       *
       * Örnek:
       * ```ts
       *  getMultilingualUrls('/about');
       *
       *  // Döndürür
       *  // {
       *  //   en: '/about',
       *  //   fr: '/fr/about',
       *  //   es: '/es/about',
       *  // }
       * ```
       */
      const multilingualUrls = getMultilingualUrls("/");
      const localizedUrl =
        multilingualUrls[locale as keyof typeof multilingualUrls];
    
      return {
        ...metadata,
        alternates: {
          canonical: localizedUrl,
          languages: { ...multilingualUrls, "x-default": "/" },
        },
        openGraph: {
          url: localizedUrl,
        },
      };
    };
    
    // ... Kodun geri kalanı
    

    next-intlayer adresinden içe aktarılan getIntlayer işlevinin, içeriğinizi visual editor ile entegrasyon sağlayan bir IntlayerNode içinde sarılı şekilde döndürdüğünü unutmayın. Buna karşılık, intlayer adresinden içe aktarılan getIntlayer işlevi, içeriğinizi ek özelliklere sahip olmaksızın doğrudan döndürür.

    Metadata optimizasyonu hakkında daha fazla bilgi için resmi Next.js dokumentasyonuna bakın.

11. 11

    Yerel Anahtarlayıcı Bileşeni Oluşturma

    sitemap.xml ve robots.txt dosyalarınızı uluslararasılaştırmak için Intlayer tarafından sağlanan getMultilingualUrls fonksiyonunu kullanabilirsiniz. Bu fonksiyon, sitemap'iniz için çok dilli URL'ler oluşturmanıza olanak tanır.

    src/app/sitemap.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import { getMultilingualUrls } from "intlayer";
    import type { MetadataRoute } from "next";
    
    const sitemap = (): MetadataRoute.Sitemap => [
      {
        url: "https://example.com",
        alternates: {
          languages: {
            ...getMultilingualUrls("https://example.com"),
            "x-default": "https://example.com",
          },
        },
      },
      {
        url: "https://example.com/login",
        alternates: {
          languages: {
            ...getMultilingualUrls("https://example.com/login"),
            "x-default": "https://example.com/login",
          },
        },
      },
      {
        url: "https://example.com/register",
        alternates: {
          languages: {
            ...getMultilingualUrls("https://example.com/register"),
            "x-default": "https://example.com/register",
          },
        },
      },
    ];
    
    export default sitemap;
    

    src/app/robots.ts

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    import type { MetadataRoute } from "next";
    import { getMultilingualUrls } from "intlayer";
    
    const getAllMultilingualUrls = (urls: string[]) =>
      urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);
    
    const robots = (): MetadataRoute.Robots => ({
      rules: {
        userAgent: "*",
        allow: ["/"],
        disallow: getAllMultilingualUrls(["/login", "/register"]),
      },
      host: "https://example.com",
      sitemap: `https://example.com/sitemap.xml`,
    });
    
    export default robots;
    

    Uygulamanızın mevcut yerel ayarı saygı göstermesini sağlamak için, bir yerel anahtarlayıcı bileşeni oluşturabilirsiniz. Bu bileşen, dahili URL'leri otomatik olarak mevcut dille önekler, böylece örneğin Fransızca konuşan bir kullanıcı "Hakkında" sayfasına bir bağlantıya tıkladığında, /fr/hakkinda yerine /hakkindaya yönlendirilir.

    Bu davranış birkaç nedenden dolayı kullanışlıdır:

    • SEO ve Kullanıcı Deneyimi: Yerelleştirilmiş URL'ler, arama motorlarının dil özel sayfalarını doğru şekilde indekslemesine yardımcı olur ve kullanıcılara tercih ettikleri dilde içerik sağlar.
    • Tutarlılık: Uygulamanız boyunca yerelleştirilmiş bir bağlantı kullanarak, navigasyonun mevcut yerel ayar içinde kalmasını garanti edersiniz, beklenmedik dil anahtarlarını önlersiniz.
    • Bakım Kolaylığı: URL yönetim mantığını tek bir bileşende merkezileştirmek, kod tabanınızı yönetmeyi ve uygulamanız büyüdükçe genişletmeyi basitleştirir.

    Aşağıda, TypeScript'te yerelleştirilmiş bir Link bileşeninin uygulanması bulunmaktadır:

    src/components/LocaleSwitcher.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    "use client";
    
    import { useRouter } from "next/navigation";
    import { useLocale } from "next-intlayer";
    import { getLocalizedUrl } from "intlayer";
    import { Locales } from "intlayer";
    
    const LocaleSwitcher = () => {
      const router = useRouter();
      const { locale } = useLocale();
    
      const handleLocaleChange = (newLocale: Locales) => {
        const pathWithoutLocale = window.location.pathname.replace(
          /^\/[a-z]{2}/,
          ""
        );
        router.push(getLocalizedUrl(pathWithoutLocale, newLocale));
      };
    
      return (
        <div>
          <h2>Dil Seçin</h2>
          <div>
            {Object.values(Locales).map((localeItem) => (
              <button
                key={localeItem}
                onClick={() => handleLocaleChange(localeItem)}
                disabled={locale === localeItem}
              >
                {localeItem.toUpperCase()}
              </button>
            ))}
          </div>
        </div>
      );
    };
    
    export default LocaleSwitcher;
    

    Alternatif bir yol, useLocale kancası tarafından sağlanan setLocale fonksiyonunu kullanmaktır. Bu fonksiyon, sayfa ön yüklemesine izin vermez ve sayfayı yeniden yükler.

    Bu durumda, router.push kullanarak yönlendirme olmadan, sadece sunucu tarafı kodunuz içeriğin yerel ayarını değiştirecektir.

    src/components/LocaleSwitcher.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    "use client";
    
    import { useRouter } from "next/navigation";
    import { useLocale } from "next-intlayer";
    import { getLocalizedUrl } from "intlayer";
    
    // ... Geri kalan kod
    
    const router = useRouter();
    const { setLocale } = useLocale({
      onLocaleChange: (locale) => {
        router.push(getLocalizedUrl(pathWithoutLocale, locale));
      },
    });
    
    return (
      <button onClick={() => setLocale(Locales.FRENCH)}>Fransızca'ya Geç</button>
    );
    

    Dokümantasyon referansları:

    • useLocale kancası
    • getLocaleName kancası
    • getLocalizedUrl kancası
    • getHTMLTextDir kancası
    • hrefLang özelliği
    • lang özelliği
    • dir özelliği
    • aria-current özelliği

12. 11

    Yerelleştirilmiş Bağlantı Bileşeni Oluşturma

    İsteğe bağlı

    Uygulamanızın navigasyonunun mevcut yerel ayarı saygı göstermesini sağlamak için, özel bir Link bileşeni oluşturabilirsiniz. Bu bileşen, dahili URL'leri otomatik olarak mevcut dille önekler, böylece örneğin Fransızca konuşan bir kullanıcı "Hakkında" sayfasına bir bağlantıya tıkladığında, /fr/hakkinda yerine /hakkindaya yönlendirilir.

    Bu davranış birkaç nedenden dolayı kullanışlıdır:

    • SEO ve Kullanıcı Deneyimi: Yerelleştirilmiş URL'ler, arama motorlarının dil özel sayfalarını doğru şekilde indekslemesine yardımcı olur ve kullanıcılara tercih ettikleri dilde içerik sağlar.
    • Tutarlılık: Uygulamanız boyunca yerelleştirilmiş bir bağlantı kullanarak, navigasyonun mevcut yerel ayar içinde kalmasını garanti edersiniz, beklenmedik dil anahtarlarını önlersiniz.
    • Bakım Kolaylığı: URL yönetim mantığını tek bir bileşende merkezileştirmek, kod tabanınızı yönetmeyi ve uygulamanız büyüdükçe genişletmeyi basitleştirir.

    Aşağıda, TypeScript'te yerelleştirilmiş bir Link bileşeninin uygulanması bulunmaktadır:

    src/components/Link.tsx

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    "use client";
    
    import { getLocalizedUrl } from "intlayer";
    import NextLink, { type LinkProps as NextLinkProps } from "next/link";
    import { useLocale } from "next-intlayer";
    import { forwardRef, PropsWithChildren, type ForwardedRef } from "react";
    
    /**
     * Verilen bir URL'nin harici olup olmadığını kontrol eden yardımcı fonksiyon.
     * URL http:// veya https:// ile başlıyorsa, harici olarak kabul edilir.
     */
    export const checkIsExternalLink = (href?: string): boolean =>
      /^https?:\/\//.test(href ?? "");
    
    /**
     * Href özelliğini mevcut yerel ayar temelinde uyarlayan özel bir Link bileşeni.
     * Dahili bağlantılar için, `getLocalizedUrl` kullanarak URL'yi yerel ayar ile önekler (örneğin, /fr/hakkinda).
     * Bu, navigasyonun aynı yerel ayar bağlamında kalmasını sağlar.
     */
    export const Link = forwardRef<
      HTMLAnchorElement,
      PropsWithChildren<NextLinkProps>
    >(({ href, children, ...props }, ref: ForwardedRef<HTMLAnchorElement>) => {
      const { locale } = useLocale();
      const isExternalLink = checkIsExternalLink(href.toString());
    
      // Bağlantı dahili ise ve geçerli bir href sağlanmışsa, yerelleştirilmiş URL'yi alın.
      const hrefI18n: NextLinkProps["href"] =
        href && !isExternalLink ? getLocalizedUrl(href.toString(), locale) : href;
    
      return (
        <NextLink href={hrefI18n} ref={ref} {...props}>
          {children}
        </NextLink>
      );
    });
    
    Link.displayName = "Link";
    

    Nasıl Çalışır

    • Harici Bağlantıları Algılama:
      Yardımcı fonksiyon checkIsExternalLink, bir URL'nin harici olup olmadığını belirler. Harici bağlantılar değişmeden bırakılır çünkü yerelleştirmeye ihtiyaçları yoktur.

    • Mevcut Yerel Ayarı Alma:
      useLocale kancası mevcut yerel ayarı sağlar (örneğin, Fransızca için fr).

    • URL'yi Yerelleştirme:
      Dahili bağlantılar (yani harici olmayan) için, getLocalizedUrl kullanarak URL'yi otomatik olarak mevcut yerel ayar ile önekler. Bu, kullanıcınız Fransızca ise, /hakkinda href'ini geçmek onu /fr/hakkindaya dönüştürür.

    • Bağlantıyı Döndürme:
      Bileşen, yerelleştirilmiş URL ile bir <a> elementi döndürür, böylece navigasyon yerel ayar ile tutarlı olur.

    Bu Link bileşenini uygulamanız boyunca entegre ederek, tutarlı ve dil bilincine sahip bir kullanıcı deneyimi sürdürürsünüzken aynı zamanda gelişmiş SEO ve kullanılabilirlikten de yararlanırsınız.

13. 12

    Sunucu Eylemlerinde (Server Actions) geçerli yerel ayarı alın

    İsteğe bağlı

    Bir Sunucu Eylemi (Server Action) içinde aktif yerel ayara ihtiyacınız varsa (örneğin, e-postaları yerelleştirmek veya yerel ayara duyarlı mantık çalıştırmak için), next-intlayer/server üzerinden getLocale fonksiyonunu ç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();
    
      // Yerel ayar ile bir şeyler yapın
    };
    

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

    1. İlk olarak, ara katman yazılımı (middleware) tarafından ayarlanmış olabilecek bir yerel ayar değeri için istek başlıklarını kontrol eder
    2. Başlıklarda yerel ayar bulunamazsa, çerezlerde saklanan bir yerel ayar arar
    3. Çerez bulunamazsa, kullanıcının tercih ettiği dili tarayıcı ayarlarından tespit etmeye çalışır
    4. Son çare olarak, uygulamanın yapılandırılmış varsayılan yerel ayarına geri döner

    Bu, mevcut bağlama göre en uygun yerel ayarın seçilmesini sağlar.

14. 13

    bundle boyutunuzu Optimize Edin

    İsteğe bağlı

    next-intlayer kullanırken, sözlükler varsayılan olarak her sayfa için pakete dahil edilir. bundle boyutunu optimize etmek için, Intlayer isteğe bağlı bir SWC eklentisi sağlar ki bu, useIntlayer çağrılarını akıllıca makrolar kullanarak değiştirir. Bu, sözlüklerin sadece onları gerçekten kullanan sayfalar için paketlere dahil edilmesini sağlar.

    Bu optimizasyonu etkinleştirmek için, @intlayer/swc paketini kurun. Kurulduktan sonra, next-intlayer eklentiyi otomatik olarak algılayacak ve kullanacaktır:

    bash

    İçeriği kopyala

    Kodu kopyala

    Kodu panoya kopyala

    npm install @intlayer/swc --save-dev
    

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

    Not: Bu paket varsayı alan olarak kurulmaz çünkü SWC eklentileri Next.js'te hala deneyseldir. Gelecekte değişebilir.

    Not: Eğer seçeneği importMode: 'dynamic' veya importMode: 'fetch' olarak ayarlarsanız (sözlük yapılandırmasında), Suspense'e dayanacaktır, bu nedenle useIntlayer çağrılarınızı bir Suspense sınırıyla sarmalamanız gerekecektir. Bu, useIntlayer'ı doğrudan Sayfa / Düzen bileşeninizin en üst düzeyinde kullanamayacağınız anlamına gelir.

TypeScript Yapılandırma

Intlayer, TypeScript'ten faydalanmak ve kod tabanınızı daha güçlü hale getirmek için modül genişletmesi kullanır.

TypeScript yapılandırmanızın otomatik olarak oluşturulan türleri içerdiğinden emin olun.

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

Git Yapılandırma

Intlayer tarafından oluşturulan dosyaları yok saymanız önerilir. Bu, onları Git deposuna göndermemenizi sağlar.

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

# Intlayer tarafından oluşturulan dosyaları yok say
.intlayer

VS Code Uzantısı

Intlayer ile geliştirme deneyiminizi geliştirmek için, resmi Intlayer VS Code Uzantısı'nı kurabilirsiniz.

VS Code Marketplace'ten Kurun

Bu uzantı şunları sağlar:

• Çeviri anahtarları için otomatik tamamlama.
• Eksik çeviriler için gerçek zamanlı hata algılama.
• Çevrilmiş içeriğin satır içi önizlemeleri.
• Çevirileri kolayca oluşturmak ve güncellemek için hızlı eylemler.

Uzantının nasıl kullanılacağı hakkında daha fazla detay için, Intlayer VS Code Uzantısı dokümantasyonuna bakın.

Daha Fazla Bilgi Edinin

Daha fazla ilerlemek için, görsel düzenleyiciyi uygulayabilir veya içeriğinizi CMS kullanarak harici hale getirebilirsiniz.