Intlayer kullanarak Vite ve Vanilla JS web sitenizi çevirin | Uluslararasılaştırma (i18n)

İçindekiler

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.
• Metadataları, rotaları ve içeriği dinamik olarak yerelleştirin.
• Otomatik olarak oluşturulan türlerle TypeScript desteği sağlayın, bu da otomatik tamamlamayı ve hata algılamayı iyileştirir.
• Dinamik yerel ayar algılama ve değiştirme gibi gelişmiş özelliklerden yararlanın.

Bir Vite ve Vanilla JS Uygulamasında Intlayer Kurulumu İçin Adım Adım Kılavuz

Adım 1: Bağımlılıkları Yükleyin

npm kullanarak gerekli paketleri yükleyin:

npm install intlayer vanilla-intlayernpm install vite-intlayer --save-devnpx 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.

• vanilla-intlayer Intlayer'ı saf JavaScript / TypeScript uygulamalarıyla entegre eden paket. Bir pub/sub singleton (IntlayerClient) ve geri çağırma tabanlı yardımcılar (useIntlayer, useLocale, vb.) sağlar, böylece uygulamanızın herhangi bir bölümü bir UI çerçevesine bağlı kalmadan yerel ayar değişikliklerine tepki verebilir.

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

Adım 2: Projenizin Yapılandırılması

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

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'leri, ara yazılım yönlendirmesini, çerez adlarını, içerik bildirimlerinizin konumunu ve uzantısını ayarlayabilir, konsoldaki Intlayer günlüklerini devre dışı bırakabilir ve daha fazlasını yapabilirsiniz. Mevcut parametrelerin tam listesi için yapılandırma belgelerine bakın.

Adım 3: Intlayer'ı Vite Yapılandırmanıza Entegre Edin

Yapılandırmanıza intlayer eklentisini ekleyin.

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [intlayer()],
});

intlayer() Vite eklentisi, Intlayer'ı Vite ile entegre etmek için kullanılır. İçerik bildirimi dosyalarının oluşturulmasını sağlar ve bunları geliştirme modunda izler. Vite uygulaması içinde Intlayer ortam değişkenlerini tanımlar. Ayrıca, performansı optimize etmek için takma adlar (aliases) sağlar.

Adım 4: Giriş noktanızda Intlayer'ı başlatın

Küresel yerel ayar singleton'ının hazır olması için herhangi bir içerik işlenmeden önce installIntlayer() işlevini çağırın.

import { installIntlayer } from "vanilla-intlayer";// Herhangi bir i18n içeriği işlenmeden önce çağrılmalıdır.installIntlayer();// Uygulama modüllerinizi içe aktarın ve çalıştırın.import "./app.js";

Ayrıca md() içerik bildirimlerini (Markdown) kullanıyorsanız, markdown oluşturucuyu da yükleyin:

import { installIntlayer, installIntlayerMarkdown } from "vanilla-intlayer";installIntlayer();installIntlayerMarkdown();import "./app.js";

Adım 5: İçeriğinizi Bildirin

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

import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Daha fazlasını öğrenmek için Vite logosuna tıklayın",
    }),
  },
} satisfies Dictionary;

export default appContent;

İçerik bildirimleriniz, contentDir dizinine (varsayılan olarak ./src) dahil oldukları sürece uygulamanızın herhangi bir yerinde tanımlanabilir. Ve içerik bildirimi dosyası uzantısıyla eşleşir (varsayılan olarak .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Daha fazla ayrıntı için içerik bildirimi belgelerine bakın.

Adım 6: JavaScript'inizde Intlayer Kullanın

vanilla-intlayer, react-intlayer yüzey API'sini yansıtır: useIntlayer(key, locale?) doğrudan çevrilmiş içeriği döndürür. Yerel ayar değişikliklerine abone olmak için sonuç üzerinde .onChange() işlevini zincirleyin - bir React yeniden oluşturmasının açık eşdeğeri.

import { installIntlayer, useIntlayer } from "vanilla-intlayer";installIntlayer();// Mevcut yerel ayar için başlangıç içeriğini alın.// Yerel ayar her değiştiğinde bildirim almak için .onChange() işlevini zincirleyin.const content = useIntlayer("app").onChange((newContent) => {  // Yalnızca etkilenen DOM düğümlerini yeniden oluşturun veya yamalayın  document.querySelector<HTMLHeadingElement>("h1")!.textContent = String(    newContent.title  );  document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =    String(newContent.readTheDocs);});// Başlangıç oluşturmadocument.querySelector<HTMLHeadingElement>("h1")!.textContent = String(  content.title);document.querySelector<HTMLParagraphElement>(".read-the-docs")!.textContent =  String(content.readTheDocs);

Yaprak değerleri String() içine sararak onlara dize olarak erişin, bu da düğümün toString() yöntemini çağırır ve çevrilmiş metni döndürür.

Yerel bir HTML özelliği (örn. alt, aria-label) için değere ihtiyacınız olduğunda, doğrudan .value kullanın:

typescript

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

img.alt = content.viteLogoLabel.value;

(İsteğe Bağlı) Adım 7: İçeriğinizin dilini değiştirin

İçeriğinizin dilini değiştirmek için useLocale tarafından sunulan setLocale işlevini kullanın.

import { getLocaleName } from "intlayer";import { useLocale } from "vanilla-intlayer";export function setupLocaleSwitcher(container: HTMLElement): () => void {  const { locale, availableLocales, setLocale, subscribe } = useLocale();  const select = document.createElement("select");  select.setAttribute("aria-label", "Language");  const render = (currentLocale: string) => {    select.innerHTML = availableLocales      .map(        (loc) =>          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>            ${getLocaleName(loc)}          </option>`      )      .join("");  };  render(locale);  container.appendChild(select);  select.addEventListener("change", () => setLocale(select.value as any));  // Başka bir yerden yerel ayar değiştiğinde açılır menüyü senkronize tutun  return subscribe((newLocale) => render(newLocale));}

(İsteğe Bağlı) Adım 8: Markdown ve HTML içeriği oluşturun

Intlayer md() ve html() içerik bildirimlerini destekler. Vanilla JS'de, derlenmiş çıktı innerHTML aracılığıyla ham HTML olarak eklenir.

HTML'yi derleyin ve ekleyin:

import {  compileMarkdown,  installIntlayerMarkdown,  useIntlayer,} from "vanilla-intlayer";installIntlayerMarkdown();const content = useIntlayer("app").onChange((newContent) => {  const el = document.querySelector<HTMLDivElement>(".edit-note")!;  el.innerHTML = compileMarkdown(String(newContent.editNote));});document.querySelector<HTMLDivElement>(".edit-note")!.innerHTML =  compileMarkdown(String(content.editNote));

TIP

String(content.editNote), IntlayerNode üzerinde ham Markdown dizesini döndüren toString() işlevini çağırır. Bir HTML dizesi almak için bunu compileMarkdown'a geçirin, ardından innerHTML aracılığıyla ayarlayın.

WARNING

innerHTML'i yalnızca güvenilir içerikle kullanın. Markdown kullanıcı girişinden geliyorsa, önce onu temizleyin (örn. DOMPurify ile). Bir temizleme oluşturucusunu dinamik olarak yükleyebilirsiniz:

typescript

İçeriği kopyala

Kodu kopyala

Kodu panoya kopyala

import { installIntlayerMarkdownDynamic } from "vanilla-intlayer";await installIntlayerMarkdownDynamic(async () => {  const DOMPurify = await import("dompurify");  return (markdown) => DOMPurify.sanitize(compileMarkdown(markdown));});

(İsteğe Bağlı) Adım 9: Uygulamanıza yerelleştirilmiş Yönlendirme ekleyin

Her dil için benzersiz yollar oluşturmak için (SEO için yararlıdır), sunucu tarafı yerel ayar algılaması için Vite yapılandırmanızda intlayerProxy kullanabilirsiniz.

İlk olarak, Vite yapılandırmanıza intlayerProxy ekleyin:

Üretimde intlayerProxy kullanmak için vite-intlayer'ı devDependencies'dan dependencies'e taşımanız gerektiğini unutmayın.

import { defineConfig } from "vite";
import { intlayer, intlayerProxy } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayerProxy(), // ilk sıraya yerleştirilmelidir
    intlayer(),
  ],
});

(İsteğe Bağlı) Adım 10: Yerel ayar değiştiğinde URL'yi değiştirin

Yerel ayar değiştiğinde tarayıcı URL'sini güncellemek için Intlayer'ı yükledikten sonra useRewriteURL() işlevini çağırın:

import { installIntlayer, useRewriteURL } from "vanilla-intlayer";installIntlayer();// URL'yi hemen ve sonraki her yerel ayar değişikliğinde yeniden yazar.// Temizlik için bir abonelikten çıkma işlevi döndürür.const stopRewriteURL = useRewriteURL();

(İsteğe Bağlı) Adım 11: HTML Dil ve Yön Özniteliklerini Değiştirin

Erişilebilirlik ve SEO için <html> etiketinin lang ve dir özniteliklerini mevcut yerel ayara uyacak şekilde güncelleyin.

import { getHTMLTextDir } from "intlayer";import { installIntlayer, useLocale } from "vanilla-intlayer";installIntlayer();useLocale({  onLocaleChange: (locale) => {    document.documentElement.lang = locale;    document.documentElement.dir = getHTMLTextDir(locale);  },});

(İsteğe Bağlı) Adım 12: Yerel ayar başına sözlükleri tembel yükleyin (Lazy-load)

Büyük uygulamalar için her yerel ayarın sözlüğünü kendi yığınına bölmek isteyebilirsiniz. Vite'in dinamik import() işleviyle birlikte useDictionaryDynamic kullanın:

import { installIntlayer, useDictionaryDynamic } from "vanilla-intlayer";installIntlayer();const unsubscribe = useDictionaryDynamic(  {    en: () => import("../.intlayer/dictionaries/en/app.mjs"),    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),    es: () => import("../.intlayer/dictionaries/es/app.mjs"),  },  "app").onChange((content) => {  document.querySelector("h1")!.textContent = String(content.title);});

Her yerel ayarın paketi yalnızca o yerel ayar etkinleştirildiğinde getirilir ve sonuç önbelleğe alınır - aynı yerel ayara sonraki geçişler anlıktır.

(İsteğe Bağlı) Adım 13: Bileşenlerinizin içeriğini dışa aktarın

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 dışa aktarmak için bir derleyici / ayıştırıcı önerir.

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

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  // ... Geri kalan yapılandırmanız  compiler: {    /**     * Derleyicinin etkinleştirilip etkinleştirilmeyeceğini belirtir.     */    enabled: true,    /**     * Çıktı dosyaları yolunu tanımlar     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Dönüştürüldükten sonra bileşenlerin kaydedilip kaydedilmeyeceğini belirtir.     * Bu şekilde, 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ı ön eki     */    dictionaryKeyPrefix: "",  },};export default config;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Derleyici eklentisini ekler ],});

npm run build # veya npm run dev

(İsteğe bağlı) Sitemap ve robots.txt (derleme zamanı üretimi)

Intlayer, generateSitemap ve getMultilingualUrls ile tarayıcılar için çok dilli sitemap.xml ve robots.txt üretip bunları public/ klasörüne otomatik yazmanıza yardımcı olur. Genelde Vite’tan önce küçük bir Node betiği çalıştırılır (ör. npm predev / prebuild kancaları).

Sitemap

Intlayer sitemap oluşturucusu yerel ayarlarınıza uyar ve tarayıcılar için metadata ekler.

Üretilen sitemap xhtml:link (hreflang) ad alanını destekler. Düz URL listesi yerine, her sayfanın tüm dil sürümleri çift yönlü bağlanır (ör. /about, /fr/about veya /about?lang=fr - yönlendirme moduna bağlı).

Robots.txt

getMultilingualUrls kullanarak Disallow kurallarının hassas yolların tüm yerelleştirilmiş varyantlarını kapsamasını sağlayın.

1. Proje köküne generate-seo.mjs ekleyin

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

Betik intlayer içe aktarabilmeli; paket kurulu olmalı. Üretimde ortam değişkeni SITE_URL ayarlayın (ör. CI).

Node ESM için generate-seo.mjs tercih edin. generate-seo.js kullanıyorsanız package.json içinde "type": "module" veya ESM’yi başka şekilde etkinleştirin.

2. Betiği Vite’tan önce çalıştırın

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

pnpm veya yarn kullanıyorsanız komutları uyarlayın. CI’dan da çağrılabilir.

TypeScript'i Yapılandırın

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

{  "compilerOptions": {    // ...  },  "include": ["src", ".intlayer/**/*.ts"],}

Git Yapılandırması

Intlayer tarafından oluşturulan dosyaların yoksayılması önerilir. Bu, onları Git deponuza göndermekten kaçınmanıza olanak tanır.

Bunu yapmak için .gitignore dosyanıza aşağıdaki talimatları 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:

• Ç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ğına dair daha fazla ayrıntı için Intlayer VS Code Uzantısı belgelerine bakın.

Daha Fazlasına Gidin

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