Yazar:
    Oluşturma:2025-12-07Son güncelleme:2026-05-31

    Intlayer ile React Router v7 (File-System Routes) çevirin | Uluslararasılaştırma (i18n)

    Bu rehber, React Router v7 projelerinde dosya sistemi tabanlı yönlendirme (@react-router/fs-routes) kullanarak yerel dil farkındalıklı yönlendirme, TypeScript desteği ve modern geliştirme uygulamaları ile sorunsuz uluslararasılaştırma için Intlayer'ın nasıl entegre edileceğini gösterir.

    İstemci tarafı yönlendirme için, Intlayer ile React Router v7 rehberine bakın.

    Table of Contents

    Neden alternatifler yerine Intlayer?

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

    Intlayer, yerel duyarlı yönlendirme, yerel algılama için ara yazılım ve ölçeklendirme uluslararasılaştırması (i18n) için gereken tüm özellikleri sunarak React Router ile mükemmel çalışacak şekilde optimize edilmiştir.

    Sayfalarınıza çok büyük JSON dosyaları yüklemek yerine yalnızca gerekli içeriği yükleyin. Intlayer bundle ve sayfa boyutlarınızı %50'ye kadar azaltmanıza yardımcı olur.

    Uygulamanızın içeriğinin kapsamını belirlemek, büyük ölçekli uygulamalar için bakımı kolaylaştırır. İçerik kod tabanınızın tamamını gözden geçirmenin zihinsel yükü olmadan, tek bir özellik klasörünü çoğaltabilir veya silebilirsiniz. Ayrıca Intlayer, içeriğinizin doğruluğunu sağlamak için tamamen tiplendirilmiş (fully typed)tır.

    İçeriğin bir arada konumlandırılması Büyük Dil Modellerinin (LLM'ler) ihtiyaç duyduğu bağlamı azaltır. Intlayer ayrıca eksik çevirileri test etmek için CLI gibi bir araç paketiyle birlikte gelirLSP, MCP ve aracı becerileri, geliştirici deneyimini (DX) yapay zeka için daha da sorunsuz hale getirmek için ajanlar.

    Maliyeti AI sağlayıcınıza ait olmak üzere seçtiğiniz LLM'yi kullanarak CI/CD işlem hattınızda çeviri yapmak için otomasyonu kullanın. Intlayer ayrıca içerik çıkarmayı otomatikleştirmek için bir derleyici ve arka planda çeviri yapmaya yardımcı olacak bir web platformu sunar.

    Büyük JSON dosyalarını bileşenlere bağlamak performans ve tepkime sorunlarına yol açabilir. Intlayer, içerik yüklemenizi derleme sırasında optimize eder.

    Bir i18n çözümünden çok daha fazlası olan Intlayer, kendi kendine barındırılan bir görsel düzenleyici ve tam CMS çok dilli içeriğinizi gerçek zamanlı olarak yönetmenize yardımcı olarak çevirmenler, metin yazarları ve diğer ekip üyeleriyle işbirliğini kusursuz hale getirir. İçerik yerel olarak ve/veya uzaktan depolanabilir.

    Dosya sistemi tabanlı rotalar ile React Router v7 uygulamasında Intlayer kurulumu için adım adım rehber

    www.youtube.com

    See Application Template on GitHub.

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

      Tercih ettiğiniz paket yöneticisini kullanarak gerekli paketleri yükleyin:

      bash
      npm install intlayer react-intlayernpm install vite-intlayer --save-devnpm install @react-router/fs-routes --save-devnpx intlayer init

      • intlayer

      • Uluslararasılaştırma araçlarını yapılandırma yönetimi, çeviri, içerik beyanı, transpile etme ve CLI komutları için sağlayan temel paket.

      • react-intlayer Intlayer'ı React uygulamasıyla entegre eden paket. React uluslararasılaştırması için bağlam sağlayıcıları ve kancalar sunar.

      • vite-intlayer Intlayer'ı Vite paketleyici ile entegre etmek için Vite eklentisini, ayrıca kullanıcının tercih ettiği yerel dili algılamak, çerezleri yönetmek ve URL yönlendirmesini işlemek için ara yazılımı içerir.

      • @react-router/fs-routes React Router v7 için dosya sistemi tabanlı yönlendirmeyi etkinleştiren paket.

    2. Projenizin Yapılandırması

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

      intlayer.config.ts
      import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    defaultLocale: Locales.ENGLISH,
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
  },
};

export default config;
      Bu yapılandırma dosyası aracılığıyla, yerelleştirilmiş URL'leri, ara yazılım yönlendirmesini, çerez isimlerini, içerik bildirimlerinizin konumunu ve uzantısını ayarlayabilir, Intlayer günlüklerini konsolda devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Mevcut parametrelerin tam listesi için yapılandırma dokümantasyonuna bakınız.

    3. Intlayer'ı Vite Yapılandırmanıza Entegre Edin

      Yapılandırmanıza intlayer eklentisini ekleyin:

      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [reactRouter(), intlayer()],});
      intlayer() Vite eklentisi, Intlayer'ı Vite ile entegre etmek için kullanılır. İçerik bildirim dosyalarının oluşturulmasını sağlar ve geliştirme modunda bunları izler. Vite uygulaması içinde Intlayer ortam değişkenlerini tanımlar. Ayrıca, performansı optimize etmek için takma adlar sağlar.

    4. React Router v7 Dosya Sistemi Rotalarını Yapılandırma

      Yönlendirme yapılandırmanızı flatRoutes ile dosya sistemi tabanlı rotalar kullanacak şekilde ayarlayın:

      app/routes.ts
      import type { RouteConfig } from "@react-router/dev/routes";import { flatRoutes } from "@react-router/fs-routes";import { configuration } from "intlayer";const routes: RouteConfig = flatRoutes({  // İçerik bildirimi dosyalarının rota olarak işlenmesini engelle  ignoredRouteFiles: configuration.content.fileExtensions.map(    (fileExtension) => `**/*${fileExtension}`  ),});export default routes;
      @react-router/fs-routes'tan gelen flatRoutes işlevi, routes/ dizinindeki dosya yapısının uygulamanızın rotalarını belirlediği dosya sistemi tabanlı yönlendirmeyi etkinleştirir. ignoredRouteFiles seçeneği, Intlayer içerik bildirimi dosyalarının (.content.ts, vb.) rota dosyaları olarak işlenmemesini sağlar.

    5. Dosya Sistemi Kuralları ile Rota Dosyaları Oluşturun

      Dosya sistemi yönlendirmesi ile, noktalar (.) yol segmentlerini temsil eden ve parantezler () isteğe bağlı segmentleri belirten düz bir adlandırma kuralı kullanırsınız.

      app/routes/ dizininizde aşağıdaki dosyaları oluşturun:

      Dosya Yapısı

      bash
      app/├── root.tsx                         # Yerel rota için layout sarmalayıcı└──routes/    ├── ($locale)._index.tsx         # Ana sayfa (/, /es, vb.)    ├── ($locale)._index.content.ts  # Ana sayfa içeriği    ├── ($locale).about.tsx          # Hakkında sayfası (/about, /es/about, vb.)    └── ($locale).about.content.ts   # Hakkında sayfası içeriği

      Adlandırma kuralları:

      • ($locale) - Yerel parametre için isteğe bağlı dinamik segment
      • _layout - Alt rotaları saran layout rotası
      • _index - İndeks rotası (üst yolda render edilir)
      • . (nokta) - Yol segmentlerini ayırır (örneğin, ($locale).about → /:locale?/about)

      Layout Bileşeni

      app/root.tsx
      import { getLocaleFromPath } from "intlayer";import { IntlayerProvider } from "react-intlayer";import {  isRouteErrorResponse,  Meta,  Outlet,  Scripts,  ScrollRestoration,  useLoaderData,} from "react-router";import type { Route } from "./+types/root";import "./app.css";// links and ErrorBoundary codeexport async function loader({ request }: Route.LoaderArgs) {  const locale = getLocaleFromPath(request.url);  return { locale };}export function Layout({  children,}: { children: React.ReactNode } & Route.ComponentProps) {  const data = useLoaderData<typeof loader>();  const { locale } = data ?? {};  return (    <html lang={locale}>      <head>        <meta charSet="utf-8" />        <meta content="width=device-width, initial-scale=1" name="viewport" />        <Meta />        <Links />      </head>      <body>        <IntlayerProvider locale={locale}>{children}</IntlayerProvider>        <ScrollRestoration />        <Scripts />      </body>    </html>  );}

      İndeks Sayfası

      app/routes/($locale)._index.tsx
      import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale)._index";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("page", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};export default function Page() {  const { title, description, aboutLink } = useIntlayer("page");  return (    <div>      <h1>{title}</h1>      <p>{description}</p>      <nav>        <LocalizedLink to="/about">{aboutLink}</LocalizedLink>      </nav>    </div>  );}

      Hakkında Sayfası

      app/routes/($locale).about.tsx
      import { getIntlayer, validatePrefix } from "intlayer";import { useIntlayer } from "react-intlayer";import { data } from "react-router";import { LocaleSwitcher } from "~/components/locale-switcher";import { Navbar } from "~/components/navbar";import type { Route } from "./+types/($locale).about";export const loader = ({ params }: Route.LoaderArgs) => {  const { locale } = params;  const { isValid } = validatePrefix(locale);  if (!isValid) {    throw data("Locale not supported", { status: 404 });  }};export const meta: Route.MetaFunction = ({ params }) => {  const content = getIntlayer("about", params.locale);  return [    { title: content.title },    { content: content.description, name: "description" },  ];};export default function AboutPage() {  const { title, content, homeLink } = useIntlayer("about");  return (    <div>      <h1>{title}</h1>      <p>{content}</p>      <nav>        <LocalizedLink to="/">{homeLink}</LocalizedLink>      </nav>    </div>  );}
      Eğer uygulamanız zaten mevcutsa, binlerce bileşeni bir saniye içinde dönüştürmek için Intlayer Compiler'ı extract komutu ile birlikte kullanabilirsiniz.

    6. İçeriğinizi Bildirin

      Çevirileri depolamak için içerik bildirimlerinizi oluşturun ve yönetin. İçerik dosyalarını rota dosyalarınızın yanına yerleştirin:

      app/routes/($locale)._index.content.ts
      import { t, type Dictionary } from "intlayer";const pageContent = {  key: "page",  content: {    title: t({      en: "Welcome to React Router v7 + Intlayer",      es: "Bienvenido a React Router v7 + Intlayer",      fr: "Bienvenue sur React Router v7 + Intlayer",    }),    description: t({      en: "Build multilingual applications with ease using React Router v7 and Intlayer.",      es: "Cree aplicaciones multilingües fácilmente usando React Router v7 y Intlayer.",      fr: "Créez des applications multilingues facilement avec React Router v7 et Intlayer.",    }),    aboutLink: t({      en: "Learn About Us",      es: "Aprender Sobre Nosotros",      fr: "En savoir plus sur nous",    }),  },} satisfies Dictionary;export default pageContent;
      app/routes/($locale).about.content.ts
      import { t, type Dictionary } from "intlayer";const aboutContent = {  key: "about",  content: {    title: t({      en: "About Us",      es: "Sobre Nosotros",      fr: "À propos de nous",    }),    content: t({      en: "This is the about page content.",      es: "Este es el contenido de la página de información.",      fr: "Ceci est le contenu de la page à propos.",    }),    homeLink: t({      en: "Home",      es: "Inicio",      fr: "Accueil",    }),  },} satisfies Dictionary;export default aboutContent;
      İçerik bildirimleriniz, uygulamanızda contentDir dizinine (varsayılan olarak ./app) dahil edildiği sürece herhangi bir yerde tanımlanabilir. Ve içerik bildirim dosya uzantısıyla eşleşmelidir (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Daha fazla detay için içerik bildirim dokümantasyonuna bakınız.

    7. Yerel Duyarlı Bileşenler Oluşturun

      Yerel duyarlı gezinme için bir LocalizedLink bileşeni oluşturun:

      app/components/localized-link.tsx
      import type { FC } from "react";import { getLocalizedUrl, type LocalesValues } from "intlayer";import { useLocale } from "react-intlayer";import { Link, type LinkProps, type To } from "react-router";const isExternalLink = (to: string) => /^(https?:)?\/\//.test(to);// Belirtilen locale göre URL'yi yerelleştirirexport const locacalizeTo = (to: To, locale: LocalesValues): To => {  if (typeof to === "string") {    if (isExternalLink(to)) {      return to;    }    return getLocalizedUrl(to, locale);  }  if (isExternalLink(to.pathname ?? "")) {    return to;  }  return {    ...to,    pathname: getLocalizedUrl(to.pathname ?? "", locale),  };};// Yerelleştirilmiş link bileşeniexport const LocalizedLink: FC<LinkProps> = (props) => {  const { locale } = useLocale();  return <Link {...props} to={locacalizeTo(props.to, locale)} />;};

      Yerelleştirilmiş rotalara gitmek istediğiniz durumlarda, useLocalizedNavigate kancasını kullanabilirsiniz:

      app/hooks/useLocalizedNavigate.ts
      import { useLocale } from "react-intlayer";import { type NavigateOptions, type To, useNavigate } from "react-router";import { locacalizeTo } from "~/components/localized-link";export const useLocalizedNavigate = () => {  const navigate = useNavigate();  const { locale } = useLocale();  const localizedNavigate = (to: To, options?: NavigateOptions) => {    const localedTo = locacalizeTo(to, locale);    navigate(localedTo, options);  };  return localizedNavigate;};

    8. Bir Dil Değiştirici Bileşeni Oluşturun

      Kullanıcıların dilleri değiştirmesine izin veren bir bileşen oluşturun:

      app/components/locale-switcher.tsx
      import type { FC } from "react";import {  getHTMLTextDir,  getLocaleName,  getLocalizedUrl,  getPathWithoutLocale,  Locales,} from "intlayer";import { useIntlayer, useLocale } from "react-intlayer";import { Link, useLocation } from "react-router";export const LocaleSwitcher: FC = () => {  const { localeSwitcherLabel } = useIntlayer("locale-switcher");  const { pathname } = useLocation();  const { availableLocales, locale } = useLocale();  const pathWithoutLocale = getPathWithoutLocale(pathname);  return (    <ol>      {availableLocales.map((localeItem) => (        <li key={localeItem}>          <Link            aria-current={localeItem === locale ? "sayfa" : undefined}            aria-label={`${localeSwitcherLabel.value} ${getLocaleName(localeItem)}`}            reloadDocument // Yeni locale'i uygulamak için sayfayı yeniden yükle            to={getLocalizedUrl(pathWithoutLocale, localeItem)}          >            <span>              {/* Yerel - örn. FR */}              {localeItem}            </span>            <span>              {/* Dil kendi yerelinde - örn. Français */}              {getLocaleName(localeItem, locale)}            </span>            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>              {/* Mevcut yerelde dil - örn. Locales.SPANISH olarak ayarlanmış mevcut yerelle Francés */}              {getLocaleName(localeItem)}            </span>            <span dir="ltr" lang={Locales.ENGLISH}>              {/* İngilizce dilinde - örn. French */}              {getLocaleName(localeItem, Locales.ENGLISH)}            </span>          </Link>        </li>      ))}    </ol>  );};
      useLocale hook'u hakkında daha fazla bilgi edinmek için belgelere bakınız.

    9. HTML Öznitelikleri Yönetimi Ekleme

      HTML lang ve dir özniteliklerini yönetmek için bir hook oluşturun:

      app/hooks/useI18nHTMLAttributes.tsx
      import { getHTMLTextDir } from "intlayer";import { useEffect } from "react";import { useLocale } from "react-intlayer";export const useI18nHTMLAttributes = () => {  const { locale } = useLocale();  useEffect(() => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  }, [locale]);};

      Bu hook, Adım 5'te gösterilen layout bileşeninde (root.tsx) zaten kullanılmaktadır.

    10. Bileşenlerinizin içeriğini çıkarın

      İsteğe bağlı

      Mevcut bir kod tabanınız varsa, binlerce dosyayı dönüştürmek zaman alıcı olabilir.

      Bu süreci kolaylaştırmak için Intlayer, bileşenlerinizi dönüştürmek ve içeriği çıkarmak için bir derleyici / çıkarıcı sunar.

      Kurulum için intlayer.config.ts dosyanıza bir compiler bölümü ekleyebilirsiniz:

      intlayer.config.ts
      import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Yapılandırmanızın geri kalanı
  compiler: {
    /**
     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.
     */
    enabled: true,

    /**
     * Çıktı dosyalarının yolunu tanımlar
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Bileşenlerin dönüştürüldükten sonra kaydedilip kaydedilmeyeceğini belirtir. Bu sayede derleyici, uygulamayı dönüştürmek için yalnızca bir kez çalıştırılabilir ve ardından kaldırılabilir.
     */
    saveComponents: false,

    /**
     * Sözlük anahtarı öneki
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

      Bileşenlerinizi dönüştürmek ve içeriği çıkarmak için çıkarıcıyı çalıştırın

      bash
      npx intlayer extract

    Configure TypeScript

    Intlayer uses module augmentation to get benefits of TypeScript and make your codebase stronger.

    Ensure your TypeScript configuration includes the autogenerated types:

    tsconfig.json
    {  // ... your existing configurations  include: [    // ... your existing includes    ".intlayer/**/*.ts", // Include the auto-generated types  ],}

    Git Configuration

    It is recommended to ignore the files generated by Intlayer. This allows you to avoid committing them to your Git repository.

    To do this, you can add the following instructions to your .gitignore file:

    .gitignore
    # Ignore the files generated by Intlayer.intlayer

    VS Code Extension

    To improve your development experience with Intlayer, you can install the official Intlayer VS Code Extension.

    Install from the VS Code Marketplace

    This extension provides:

    • Autocompletion for translation keys.
    • Real-time error detection for missing translations.
    • Inline previews of translated content.
    • Quick actions to easily create and update translations.

    For more details on how to use the extension, refer to the Intlayer VS Code Extension documentation.

    Go Further

    To go further, you can implement the visual editor or externalize your content using the CMS.

    Documentation References

    This comprehensive guide provides everything you need to integrate Intlayer with React Router v7 using file-system based routing for a fully internationalized application with locale-aware routing and TypeScript support.

    1. Middleware ekleyin

      Ayrıca uygulamanıza sunucu tarafı yönlendirme eklemek için intlayerProxy kullanabilirsiniz. Bu eklenti, URL'ye göre geçerli yerel ayarı otomatik olarak algılar ve uygun yerel ayar çerezini ayarlar. Hiçbir yerel ayar belirtilmemişse, eklenti kullanıcının tarayıcı dil tercihlerine göre en uygun yerel ayarı belirler. Hiçbir yerel ayar algılanmazsa, varsayılan yerel ayara yönlendirme yapar.

      Üretimde intlayerProxy kullanmak için, vite-intlayer paketini devDependencies'den dependencies'e geçirmeniz gerektiğini unutmayın.
      vite.config.ts
      import { reactRouter } from "@react-router/dev/vite";import { defineConfig } from "vite";import { intlayer, intlayerProxy } from "vite-intlayer";export default defineConfig({  plugins: [    intlayerProxy(), // should be placed first    reactRouter(),    intlayer(),  ],});

    TypeScript'i Yapılandırma

    Intlayer, TypeScript'in avantajlarından yararlanmak ve kod tabanınızı daha güçlü hale getirmek için modül genişletme (module augmentation) kullanır.

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

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

    Git Yapılandırması

    Intlayer tarafından oluşturulan dosyaların göz ardı edilmesi önerilir. Bu, bu dosyaların Git deposuna eklenmesini önlemenizi sağlar.

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

    .gitignore
    # Intlayer tarafından oluşturulan dosyaları göz ardı et.intlayer

    VS Code Eklentisi

    Intlayer ile geliştirme deneyiminizi iyileştirmek için resmi Intlayer VS Code Eklentisini yükleyebilirsiniz.

    VS Code Marketplace'ten Yükleyin

    Bu eklenti şunları sağlar:

    • Çeviri anahtarları için Otomatik Tamamlama.
    • Eksik çeviriler için Gerçek Zamanlı Hata Tespiti.
    • Çevrilmiş içeriğin Satır İçi Önizlemeleri.
    • Çevirileri kolayca oluşturup güncellemek için Hızlı İşlemler.

    Eklentinin nasıl kullanılacağı hakkında daha fazla bilgi için Intlayer VS Code Eklentisi dokümantasyonuna bakabilirsiniz.

    Daha İleri Gitmek İçin

    Daha ileri gitmek için, görsel editörü uygulayabilir veya içeriğinizi CMS kullanarak dışa aktarabilirsiniz.

    Dokümantasyon Referansları

    Bu kapsamlı rehber, dosya sistemi tabanlı yönlendirme kullanarak React Router v7 ile Intlayer'ı entegre etmeniz için ihtiyacınız olan her şeyi sağlar, böylece yerel dil farkındalıklı yönlendirme ve TypeScript desteği ile tamamen uluslararasılaştırılmış bir uygulama elde edersiniz.

    React Router v7Compiler