Creation:2025-09-07Last update:2026-05-31

    Intlayer ile Create React App çevirin | Uluslararasılaştırma (i18n)

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

    Intlayer Nedir?

    Intlayer, modern web uygulamalarında çok dilli desteği basitleştirmek için tasarlanmış yenilikçi, açık kaynaklı bir uluslararasılaştırma (i18n) kütüphanesidir.

    Intlayer ile şunları yapabilirsiniz:

    • Bileşen düzeyinde bildirimsel sözlükler kullanarak çevirileri kolayca yönetin.
    • Meta verileri, rotaları ve içeriği dinamik olarak yerelleştirin.
    • Otomatik oluşturulan türlerle TypeScript desteği sağlayın, otomatik tamamlama ve hata algılamayı iyileştirin.
    • Dinamik yerel algılama ve değiştirme gibi gelişmiş özelliklerden yararlanın.

    React Uygulamasında Intlayer'ı Kurmak İçin Adım Adım Kılavuz

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

      Gerekli paketleri npm kullanarak yükleyin:

      bash
      npm install intlayer react-intlayer react-scripts-intlayernpx intlayer init

      • intlayer

        Yapılandırma yönetimi, çeviri, içerik bildirimi, transpilasyon ve CLI komutları için uluslararasılaştırma araçları 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 hook'lar sağlar.

      • react-scripts-intlayer

        Create React App tabanlı uygulama ile Intlayer'ı entegre etmek için react-scripts-intlayer komutlarını ve eklentileri içerir. Bu eklentiler craco tabanlıdır ve Webpack paketleyici için ek yapılandırma içerir.

    2. Projenizi Yapılandırın

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

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Diğer yerel ayarlarınız
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

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

    3. Intlayer'ı CRA Yapılandırmanızda Entegre Edin

      Betiklerinizi Intlayer kullanacak şekilde değiştirin

      package.json
        "scripts": {    "build": "react-scripts-intlayer build",    "start": "react-scripts-intlayer start",    "transpile": "intlayer build"  },
      react-scripts-intlayer betikleri CRACO tabanlıdır. Kendi kurulumunuzu CRACO'nun intlayer eklentisi temel alarak da uygulayabilirsiniz. Örneğe buradan bakın.

    4. İçeriğinizi Bildirin

      Çevirileri depolamak için içerik bildirimlerinizi oluşturun ve yönetin:

      src/app.content.tsx
      import { t, type Dictionary } from "intlayer";
import React, { type ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      en: (
        <>
          <code>src/App.tsx</code>'i düzenleyin ve kaydedin
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} satisfies Dictionary;

export default appContent;
      İçerik bildirimleriniz uygulamanızda herhangi bir yerde tanımlanabilir, yeter ki contentDir dizinine dahil edilsinler (varsayılan olarak ./src). Ve içerik bildirim dosyası uzantısıyla eşleşsinler (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).
      Daha fazla detay için içerik bildirimi dokümantasyonuna bakın.
      Eğer içerik dosyanız TSX kodu içeriyorsa, içerik dosyanıza import React from "react"; içe aktarmayı düşünün.

    5. Kodunuzda Intlayer'ı Kullanın

      İçerik sözlüklerinize uygulamanız genelinde erişin:

      src/App.tsx
      import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="logo" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;
      Not: Eğer içeriğinizi bir string özniteliğinde kullanmak istiyorsanız, alt, title, href, aria-label vb. gibi, fonksiyonun değerini çağırmanız gerekir:
      html
      <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 için dokümantasyona bakın.

    6. İçeriğinizin Dilini Değiştirin

      İsteğe bağlı

      İçeriğinizin dilini değiştirmek için, useLocale hook'u tarafından sağlanan setLocale fonksiyonunu kullanabilirsiniz. Bu fonksiyon, uygulamanın yerel ayarını ayarlamanıza ve içeriği buna göre güncellemenize izin verir.

      src/components/LocaleSwitcher.tsx
      import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.English)}>
      Dili İngilizce'ye değiştir
    </button>
  );
};
      useLocale hook'u hakkında daha fazla bilgi için dokümantasyona bakın.

    7. Uygulamanıza Yerelleştirilmiş Yönlendirme Ekleyin

      İsteğe bağlı

      Bu adımın amacı, her dil için benzersiz rotalar oluşturmaktır. Bu, SEO ve SEO dostu URL'ler için yararlıdır. Örnek:

      plaintext
      - https://example.com/about- https://example.com/es/about- https://example.com/fr/about
      Varsayılan olarak, rotalar varsayılan yerel ayar için öneklenmez. Varsayılan yerel ayarı öneklemek istiyorsanız, yapılandırmanızda middleware.prefixDefault seçeneğini true olarak ayarlayabilirsiniz. Daha fazla bilgi için yapılandırma dokümantasyonuna bakın.

      Uygulamanıza yerelleştirilmiş yönlendirme eklemek için, uygulamanızın rotalarını saran ve yerel tabanlı yönlendirmeyi işleyen bir LocaleRouter bileşeni oluşturabilirsiniz. React Router kullanarak bir örnek aşağıda verilmiştir:

      src/components/LocaleRouter.tsx
      // Gerekli bağımlılıkları ve fonksiyonları içe aktar
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Intlayer'dan yardımcı fonksiyonlar ve türler
// Intlayer'dan yardımcı fonksiyonlar ve türler
import type { FC, PropsWithChildren } from "react"; // React fonksiyonel bileşenler ve prop türleri
import { IntlayerProvider } from "react-intlayer"; // Uluslararasılaştırma bağlam sağlayıcısı
import {
  BrowserRouter,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Navigasyon yönetimi için yönlendirici bileşenleri

// Yapılandırmayı Intlayer'dan çıkar
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * Yerelleştirmeyi işleyen ve çocukları uygun yerel bağlamla saran bir bileşen.
 * URL tabanlı yerel algılama ve doğrulama yönetir.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Geçerli URL yolunu al

  // Sağlanmadıysa varsayılan yerel ayara geri dön
  const currentLocale = locale ?? defaultLocale;

  // Temel bir yol oluşturmak için yoldan yerel öneki kaldır
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Geçerli URL yolu
  );

  /**
   * middleware.prefixDefault true ise, varsayılan yerel ayar her zaman öneklenmelidir.
   */
  if (middleware.prefixDefault) {
    // Yerel ayarı doğrula
    if (!locale || !locales.includes(locale)) {
      // Güncellenmiş yol ile varsayılan yerel ayara yönlendir
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Geçerli geçmişi yeni olanla değiştir
        />
      );
    }

    // Çocukları IntlayerProvider ile sar ve geçerli yerel ayarı ayarla
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * middleware.prefixDefault false olduğunda, varsayılan yerel ayar öneklenmez.
     * Geçerli yerel ayar geçerli olduğundan ve varsayılan yerel ayar olmadığından emin ol.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Varsayılan yerel ayarı hariç tut
        )
        .includes(currentLocale) // Geçerli yerel ayar geçerli yerel ayarlar listesinde mi kontrol et
    ) {
      // Yerel önek olmadan yola yönlendir
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Çocukları IntlayerProvider ile sar ve geçerli yerel ayarı ayarla
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * Yerel ayarlara özel rotalar ayarlayan bir yönlendirici bileşen.
 * React Router kullanarak navigasyonu yönetir ve yerelleştirilmiş bileşenleri işler.
 */
export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
  <BrowserRouter>
    <Routes>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Yerel ayarı yakalayan rota deseni (ör. /en/, /fr/) ve sonraki tüm yolları eşleştir
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Çocukları yerel yönetimle sar
          />
        ))}

      {
        // Varsayılan yerel ayar önekleme devre dışıysa, çocukları doğrudan kök yolda işle
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Çocukları yerel yönetimle sar
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

      Ardından, LocaleRouter bileşenini uygulamanızda kullanabilirsiniz:

      src/App.tsx
      import { LocaleRouter } from "./components/LocaleRouter";
import type { FC } from "react";

// ... AppContent bileşeniniz

const App: FC = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

    8. Yerel Ayar Değiştiğinde URL'yi Değiştirin

      İsteğe bağlı

      Yerel ayar değiştiğinde URL'yi değiştirmek için, useLocale hook'u tarafından sağlanan onLocaleChange prop'unu kullanabilirsiniz. Paralel olarak, URL yolunu güncellemek için react-router-dom'dan useLocation ve useNavigate hook'larını kullanabilirsiniz.

      src/components/LocaleSwitcher.tsx
      import { useLocation, useNavigate } from "react-router-dom";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "react-intlayer";
import { type FC } from "react";

const LocaleSwitcher: FC = () => {
  const { pathname, search } = useLocation(); // Geçerli URL yolunu al. Örnek: /fr/about?foo=bar
  const navigate = useNavigate();

  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (locale) => {
      // Güncellenmiş yerel ayar ile URL'yi oluştur
      // Örnek: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);

      // URL yolunu güncelle
      navigate(pathWithLocale);
    },
  });

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(location.pathname, localeItem)}
            hrefLang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
            }}
            key={localeItem}
          >
            <span>
              {/* Yerel ayar - örn. FR */}
              {localeItem}
            </span>
            <span>
              {/* Kendi yerel ayarındaki dil - örn. Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Geçerli yerel ayar set edildiğinde İspanyolca'da Francés - örn. */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* İngilizce'de dil - örn. French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </a>
        ))}
      </div>
    </div>
  );
};

      Dokümantasyon referansları:

    9. HTML Dil ve Yön Özniteliklerini Değiştirin

      İsteğe bağlı

      Uygulamanız birden fazla dili desteklediğinde, <html> etiketinin lang ve dir özniteliklerini geçerli yerel ayarla eşleşecek şekilde güncellemek çok önemlidir.

      Bunu otomatik olarak işlemek için bir hook oluşturabilirsiniz.

      Hook'u Uygulama

      HTML özniteliklerini yönetmek için özel bir hook oluşturun. Hook, yerel ayar değişikliklerini dinler ve öznitelikleri buna göre günceller:

      src/hooks/useI18nHTMLAttributes.tsx
      import { useEffect } from "react";
import { useLocale } from "react-intlayer";
import { getHTMLTextDir } from "intlayer";

/**
 * Geçerli yerel ayara göre HTML <html> etiketinin `lang` ve `dir` özniteliklerini günceller.
 * - `lang`: Tarayıcılara ve arama motorlarına sayfanın dilini bildirir.
 * - `dir`: Arapça veya İbranice gibi diller için 'rtl' gibi doğru okuma sırasını sağlar.
 *
 * Bu dinamik güncelleme, uygun metin işleme, erişilebilirlik ve SEO için gereklidir.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Dil özniteliğini geçerli yerel ayara güncelle
    document.documentElement.lang = locale;

    // Geçerli yerel ayara göre metin yönünü ayarla
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

      Hook'u Uygulamanızda Kullanma

      HTML özniteliklerinin yerel ayar her değiştiğinde güncellenmesi için hook'u ana bileşeninizde entegre edin:

      src/App.tsx
      import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./App.css";

const AppContent: FC = () => {
  // Hook'u kullanarak yerel ayara göre <html> etiketinin lang ve dir özniteliklerini güncelleyin.
  useI18nHTMLAttributes();

  // ... Bileşeninizin geri kalanı
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

      Bu değişiklikleri uygulayarak, uygulamanız:

      • Dil (lang) özniteliğinin SEO ve tarayıcı davranışı için doğru geçerli yerel ayarı yansıtmasını sağlar.
      • Metin yönü (dir) özniteliğini yerel ayara göre ayarlar, Arapça veya İbranice gibi farklı okuma sırasına sahip diller için okunabilirliği geliştirir.
      • Daha erişilebilir bir deneyim sağlar, çünkü yardımcı teknolojiler bu özniteliklere optimum şekilde çalışmak için güvenir.

    TypeScript'i Yapılandırın

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

    Autocompletion

    Translation error

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

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

    Git Yapılandırması

    Intlayer tarafından oluşturulan dosyaları yok saymanız önerilir. Bu, onları Git deponuza commit etmenizi önler.

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

    .gitignore
    # Intlayer tarafından oluşturulan dosyaları yok say.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:

    • Ç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 Gidin

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

    Analog
    React Native ve Expo