Yazar:
    Aymeric PINEAU
    Oluşturma:2026-03-20Son güncelleme:2026-05-31

    Storybook ile Intlayer

    İçindekiler

    Neden alternatifler yerine Intlayer?

    'storybook-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, çok dilli hikaye dekoratörleri, yerel değiştirme ve tasarım sisteminizde uluslararasılaştırmayı (i18n) ölçeklendirmek için gereken tüm özellikleri sunarak Storybook 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 agent skills, 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.

    Neden Storybook ile Intlayer Kullanmalısınız?

    Storybook, UI bileşenlerini izole bir şekilde geliştirmek ve belgelemek için endüstri standardı bir araçtır. Intlayer ile birleştirmek şunları yapmanızı sağlar:

    • Her dili önizleyin doğrudan Storybook tuvali içinde bir araç çubuğu değiştiricisi kullanarak.
    • Eksik çevirileri yakalayın üretime ulaşmadan önce.
    • Çok dilli bileşenleri belgeleyin sabit kodlanmış dizeler yerine gerçek, tür açısından güvenli (type-safe) içeriklerle.

    Adım Adım Kurulum

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

      bash
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev
      Paket Rol
      intlayer Çekirdek - yapılandırma, içerik derleme, CLI
      react-intlayer React bağlamaları - IntlayerProvider, useIntlayer hook
      vite-intlayer Vite eklentisi - içerik bildirim dosyalarını izler ve derler

    2. Bir Intlayer Yapılandırması Oluşturun

      Projenizin kök dizinine (veya tasarım sistemi paketinizin içine) intlayer.config.ts dosyasını oluşturun:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // gerektiğinde daha fazla dil ekleyin
    ],
    defaultLocale: Locales.ENGLISH,
  },
  content: {
    contentDir: ["./src"], // *.content.ts dosyalarınızın bulunduğu yer
  },
};

export default config;
      Seçeneklerin tam listesi için yapılandırma referansına bakın.

    3. Storybook'a Vite Eklentisini Ekleyin

      Storybook'un viteFinal kancası, dahili Vite yapılandırmasını genişletmenize olanak tanır. Oraya intlayer() eklentisini içe aktarın ve ekleyin:

      .storybook/main.ts
      import type { StorybookConfig } from "@storybook/react-vite";
import { defineConfig, mergeConfig } from "vite";
import { intlayer } from "vite-intlayer";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  addons: [
    "@storybook/addon-essentials",
    // …diğer eklentiler
  ],
  framework: {
    name: "@storybook/react-vite",
    options: {},
  },

  async viteFinal(baseConfig, { configType }) {
    const env = {
      command: configType === "DEVELOPMENT" ? "serve" : "build",
      mode: configType === "DEVELOPMENT" ? "development" : "production",
    } as const;

    const viteConfig = defineConfig(() => ({
      plugins: [
        intlayer({
          proxy: {
            ignore: (req) => req.url?.startsWith("/api"),
          },
        }),
      ],
    }));

    return mergeConfig(baseConfig, viteConfig(env));
  },
};

export default config;

      intlayer() eklentisi *.content.ts dosyalarınızı izler ve Storybook geliştirme sırasında herhangi bir değişiklik olduğunda sözlükleri otomatik olarak yeniden oluşturur.

    4. `IntlayerProvider` Dekoratörünü ve Bir Yerel Araç Çubuğunu Ekleyin

      Storybook'un preview dosyası, her hikayeyi IntlayerProvider ile sarmalamak ve araç çubuğunda bir dil değiştirici göstermek için doğru yerdir:

      .storybook/preview.tsx
      import type { Preview, StoryContext } from "@storybook/react";
import { IntlayerProvider } from "react-intlayer";

const preview: Preview = {
  // Her hikayeyi IntlayerProvider içinde sarmalayın
  decorators: [
    (Story, context: StoryContext) => {
      const locale = context.globals.locale ?? "en";
      return (
        <IntlayerProvider locale={locale}>
          <Story />
        </IntlayerProvider>
      );
    },
  ],

  // Storybook araç çubuğunda bir dil değiştirici gösterin
  globalTypes: {
    locale: {
      description: "Aktif dil",
      defaultValue: "en",
      toolbar: {
        title: "Dil",
        icon: "globe",
        items: [
          { value: "en", title: "English" },
          { value: "fr", title: "Français" },
          { value: "es", title: "Español" },
        ],
        dynamicTitle: true,
      },
    },
  },

  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;
      locale değerleri, intlayer.config.ts dosyanızda bildirilen dillerle eşleşmelidir.

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

      bash
      npm install intlayer react-intlayer
npm install @intlayer/webpack --save-dev

    2. Bir Intlayer Yapılandırması Oluşturun

      Projenizin kök dizinine intlayer.config.ts dosyasını oluşturun:

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

const config: IntlayerConfig = {
  internationalization: {
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
    defaultLocale: Locales.ENGLISH,
  },
  content: {
    contentDir: ["./src"],
  },
};

export default config;

    3. Storybook'un Webpack'ini Yapılandırın

      Webpack tabanlı Storybook kurulumları için (örneğin @storybook/react-webpack5), Intlayer takma adlarını ve yükleyiciyi eklemek için webpackFinal aracılığıyla webpack yapılandırmasını genişletin:

      .storybook/main.ts
      import type { StorybookConfig } from "@storybook/react-webpack5";
import { IntlayerPlugin } from "@intlayer/webpack";

const config: StorybookConfig = {
  stories: ["../src/**/*.stories.@(js|jsx|ts|tsx)"],
  addons: ["@storybook/addon-essentials"],
  framework: {
    name: "@storybook/react-webpack5",
    options: {},
  },

  webpackFinal: async (baseConfig) => {
    baseConfig.plugins = [...(baseConfig.plugins ?? []), new IntlayerPlugin()];
    return baseConfig;
  },
};

export default config;

    4. `IntlayerProvider` Dekoratörünü ve Bir Yerel Araç Çubuğunu Ekleyin

      Vite kurulumuyla aynıdır - dekoratörü ve genel dil türünü .storybook/preview.tsx dosyasına ekleyin:

      .storybook/preview.tsx
      import type { Preview, StoryContext } from "@storybook/react";
import { IntlayerProvider } from "react-intlayer";

const preview: Preview = {
  decorators: [
    (Story, context: StoryContext) => {
      const locale = context.globals.locale ?? "en";
      return (
        <IntlayerProvider locale={locale}>
          <Story />
        </IntlayerProvider>
      );
    },
  ],

  globalTypes: {
    locale: {
      description: "Aktif dil",
      defaultValue: "en",
      toolbar: {
        title: "Dil",
        icon: "globe",
        items: [
          { value: "en", title: "English" },
          { value: "fr", title: "Français" },
          { value: "es", title: "Español" },
        ],
        dynamicTitle: true,
      },
    },
  },
};

export default preview;

    İçerik Bildirme

    Her bileşenin yanına bir *.content.ts dosyası oluşturun. Intlayer derleme sırasında bunu otomatik olarak algılar.

    src/components/CopyButton/CopyButton.content.ts
    import { type Dictionary, t } from "intlayer";

const copyButtonContent = {
  key: "copy-button",
  content: {
    label: t({
      en: "Copy content",
      fr: "Copier le contenu",
      es: "Copiar contenido",
    }),
  },
} satisfies Dictionary;

export default copyButtonContent;
    Daha fazla içerik bildirimi formatı ve özelliği için içerik bildirimi dokümantasyonuna bakın.

    Bir Bileşende useIntlayer Kullanımı

    src/components/CopyButton/index.tsx
    "use client";

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

type CopyButtonProps = {
  content: string;
};

export const CopyButton: FC<CopyButtonProps> = ({ content }) => {
  const { label } = useIntlayer("copy-button");

  return (
    <button
      onClick={() => navigator.clipboard.writeText(content)}
      aria-label={label.value}
      title={label.value}
    >
      Kopyala
    </button>
  );
};

    useIntlayer, en yakın IntlayerProvider tarafından sağlanan geçerli dil için derlenmiş sözlüğü döndürür. Storybook araç çubuğunda dili değiştirmek, hikayeyi güncellenmiş çevirilerle otomatik olarak yeniden oluşturur.

    Uluslararasılaştırılmış Bileşenler İçin Hikayeler Yazma

    IntlayerProvider dekoratörü devredeyken, hikayeleriniz daha önce olduğu gibi çalışır. Dil araç çubuğu tüm tuval için aktif dili kontrol eder:

    src/components/CopyButton/CopyButton.stories.tsx
    import type { Meta, StoryObj } from "@storybook/react";
import { CopyButton } from ".";

const meta: Meta<typeof CopyButton> = {
  title: "Components/CopyButton",
  component: CopyButton,
  tags: ["autodocs"],
  argTypes: {
    content: { control: "text" },
  },
};

export default meta;
type Story = StoryObj<typeof CopyButton>;

/** Varsayılan hikaye - çevirileri önizlemek için araç çubuğunda dili değiştirin. */
export const Default: Story = {
  args: {
    content: "npm install intlayer react-intlayer",
  },
};

/** Butonu bir kod bloğu içinde oluşturur; yaygın bir gerçek dünya kullanım durumu. */
export const InsideCodeBlock: Story = {
  render: (args) => (
    <div style={{ position: "relative", display: "inline-block" }}>
      <pre style={{ background: "#1e1e1e", color: "#fff", padding: "1rem" }}>
        <code>{args.content}</code>
      </pre>
      <CopyButton
        content={args.content}
        style={{ position: "absolute", top: 8, right: 8 }}
      />
    </div>
  ),
  args: {
    content: "npx intlayer init",
  },
};
    Her hikaye araç çubuğundan locale küreselini devralır, böylece herhangi bir hikaye kodunu değiştirmeden her dili doğrulayabilirsiniz.

    Hikayelerde Çevirileri Test Etme

    Belirli bir dil için doğru çevrilmiş metnin oluşturulduğunu iddia etmek için Storybook'un play işlevlerini kullanın:

    src/components/CopyButton/CopyButton.stories.tsx
    import type { Meta, StoryObj } from "@storybook/react";
import { expect, within } from "@storybook/test";
import { CopyButton } from ".";

const meta: Meta<typeof CopyButton> = {
  title: "Components/CopyButton",
  component: CopyButton,
  tags: ["autodocs"],
};

export default meta;
type Story = StoryObj<typeof CopyButton>;

export const AccessibleLabel: Story = {
  args: { content: "Hello World" },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole("button");

    // Butonun boş olmayan erişilebilir bir adı olduğunu doğrulayın
    await expect(button).toHaveAccessibleName();
    // Butonun devre dışı olmadığını doğrulayın
    await expect(button).not.toBeDisabled();
    // Klavye erişilebilirliğini doğrulayın
    await expect(button).toHaveAttribute("tabindex", "0");
  },
};

    Ek Kaynaklar

    Neden Intlayer?