@intlayer/docs 9.4.2 → 9.4.3

package/blog/tr/date_time_number_formatting_locales.md

@@ -0,0 +1,216 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Intl ile Dillere Göre Tarih ve Sayı Formatlama"
+description: Muhtemelen ayrı bir formatlama kütüphanesine ihtiyacınız yok. Intl'in dillere göre tarih, sayı, para birimi ve listeleri nasıl işlediğini, önbelleğe alma maliyetini ve canlı ortamdaki saat dilimi hatasını öğrenin.
+keywords:
+  - dile göre tarih formatla
+  - Intl.DateTimeFormat
+  - Intl.NumberFormat
+  - toLocaleDateString
+  - yerel para birimi formatı
+  - göreceli zaman formatı
+slugs:
+  - blog
+  - date-time-number-formatting-locales
+author: aymericzip
+---
+
+# Intl ile Dillere Göre Tarih ve Sayı Formatlama
+
+Metin dizelerini çevirmek uluslararasılaştırmanın (i18n) yalnızca görünen yarısıdır. Sürekli hata bildirimleri üreten diğer yarısı ise formatlamadır: Alman bir kullanıcının `1.234,56` yerine `1,234.56` görmesi, Japon bir kullanıcının `08/02/2026` tarihini Ağustos olarak okuması veya bir tarihin sunucuda ve istemcide farklı render edilerek React hidrasyon hatasıyla sayfayı çökertmesi.
+
+Bunların hiçbiri için harici bir kütüphaneye ihtiyacınız yoktur. `Intl` API'si hedeflediğiniz tüm modern çalışma zamanlarında yerel olarak mevcuttur.
+
+## İçindekiler
+
+<TOC/>
+
+## Kendi yazdığınız tarih yardımcı fonksiyonlarını silerek başlayın
+
+Neredeyse her kod tabanında, yerelleştirme düşünülmeden önce yazılmış bir `formatDate` fonksiyonu bulunur. Bu fonksiyonlar belirli bir sırayı, bir ayırıcıyı ve genellikle İngilizce ay adlarını koda sabitler.
+
+```ts
+// Silinmesi gereken kod:
+const formatDate = (d: Date) =>
+  `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`;
+```
+
+`Intl.DateTimeFormat` bunun yerini eksiksiz alır ve her dilde doğru sonucu üretir:
+
+```ts
+new Intl.DateTimeFormat("de-DE", { dateStyle: "long" }).format(date);
+// "2. August 2026"
+new Intl.DateTimeFormat("ja-JP", { dateStyle: "long" }).format(date);
+// "2026年8月2日"
+```
+
+Aynı durum sayılar için de geçerlidir. `toFixed(2)` her yerde `1234.56` üretir, bu da Avrupa'nın büyük bölümünde hatalıdır.
+
+## `Intl` Neleri Kapsar?
+
+| API                       | Kullanım Amacı                                              |
+| :------------------------ | :---------------------------------------------------------- |
+| `Intl.DateTimeFormat`     | Tarih ve saatler (`dateStyle` / `timeStyle` hazır ayarları) |
+| `Intl.NumberFormat`       | Ondalıklar, para birimi, yüzde, birimler, kompakt gösterim  |
+| `Intl.RelativeTimeFormat` | "3 gün önce", "2 saat içinde"                               |
+| `Intl.ListFormat`         | "a, b ve c" listelemeleri                                   |
+| `Intl.PluralRules`        | Bir sayının hangi çoğul kategorisine girdiğini belirleme    |
+| `Intl.Collator`           | Dizeleri dile uygun kurallarla doğru sıralama               |
+
+`Intl.Collator` en sık unutulan araçtır. Dizeler üzerinde düz `array.sort()` çağırmak Unicode kod noktası sırasını kullanır, bu da noktalı ve aksanlı harflerin `z` harfinden sonraya atılmasına ve İsveççe `ö` harfinin yanlış yere gitmesine yol açar. Kullanıcıya gösterilen listeleri sıralarken mutlaka collator kullanın.
+
+```ts
+["zebra", "édouard", "apple"].sort(new Intl.Collator("tr").compare);
+// ["apple", "édouard", "zebra"]
+```
+
+## Elle oluşturulan seçenekler yerine hazır ayarları (presets) tercih edin
+
+`dateStyle` ve `timeStyle`, sıranın ve ayırıcıların dile göre otomatik belirlenmesini sağlar. `year`, `month` ve `day` parametrelerini tek tek belirtmek, genellikle istememeniz gereken bir kontrol sağlar; çünkü doğru sıralama bölgeye göre değişir ve CLDR verilerini kendi varsayımlarınızla ezmiş olursunuz.
+
+```ts
+// Biçimi dil belirler:
+new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(d);
+
+// Biçimi siz belirlersiniz ve başka ülkelerde hatalı olur:
+new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+}).format(d);
+```
+
+Yalnızca dar bir tablo sütunu gibi tasarımın kesinlikle sabit bir genişlik gerektirdiği durumlarda bileşenleri açıkça belirtin.
+
+## Formatlayıcı nesneleri oluşturmak maliyetlidir
+
+Performans açısından dikkat edilmesi gereken asıl detay budur. Bir `Intl.NumberFormat` oluşturmak yerel dil verilerini yüklemeyi gerektirir ve bu işlem ardından gelen `.format()` çağrısından çok daha maliyetlidir. Bunu bir render döngüsünde bin satır üzerinde tekrarlamak ciddi yavaşlamaya neden olur.
+
+```ts
+// Her satırda formatlayıcıyı yeniden oluşturur (yavaş):
+rows.map((r) => new Intl.NumberFormat(locale).format(r.total));
+
+// Bir kez oluştur ve yeniden kullan (hızlı):
+const nf = new Intl.NumberFormat(locale);
+rows.map((r) => nf.format(r.total));
+```
+
+`toLocaleDateString()` ve `toLocaleString()` fonksiyonlarının içinde de aynı sorun gizlidir: her çağrı yeni bir formatlayıcı oluşturur. Tek bir değer için sorun olmasa da listeler için yanlıştır.
+
+Dil ve seçenek kombinasyonuna göre önbelleğe alın:
+
+```ts
+const cache = new Map<string, Intl.NumberFormat>();
+
+const getNumberFormat = (
+  locale: string,
+  options: Intl.NumberFormatOptions = {}
+) => {
+  const key = `${locale}:${JSON.stringify(options)}`;
+  let formatter = cache.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat(locale, options);
+    cache.set(key, formatter);
+  }
+  return formatter;
+};
+```
+
+## Yalnızca canlı ortamda ortaya çıkan saat dilimi (timezone) hatası
+
+Bu hata geliştiricilerin günlerini tüketebilir. Sunucu SSR sırasında tarihi render eder, tarayıcı istemcide hidrasyonu gerçekleştirir ve iki taraf farklı metinler ürettiği için React bir hydration mismatch hatası fırlatır.
+
+Bunun nedeni, açıkça belirtmediğinizde `Intl.DateTimeFormat`'ın sistem saat dilimini kullanmasıdır. Canlı sunucunuz UTC saat diliminde çalışırken yerel geliştirme makineniz yerel saat dilimindedir. Bu nedenle hata yerelde görünmez ve yalnızca canlı ortamda ortaya çıkar.
+
+```ts
+// UTC sunucu ile yerel saatteki tarayıcı uyuşmaz. Hidrasyon hatası:
+new Intl.DateTimeFormat(locale, { dateStyle: "short" }).format(d);
+
+// Her iki ortam tam olarak uyuşur:
+new Intl.DateTimeFormat(locale, { dateStyle: "short", timeZone: "UTC" }).format(
+  d
+);
+```
+
+Üç uygulanabilir yaklaşım:
+
+- Sunucuda **saat dilimini sabitleyin** ve açıkça iletin. Kararlı ve belirleyicidir, ancak herkes UTC görür.
+- **Yalnızca istemcide render edin**, sunucu geçişinde sabit bir yer tutucu (placeholder) kullanın. Kullanıcıya göre doğrudur, ancak hafif bir görsel sıçrama yaratır.
+- **Kullanıcının saat dilimini saklayın** ve her iki tarafa da iletin. En iyi sonuçtur ancak daha fazla iş gerektirir.
+
+Hangisini seçerseniz seçin, hem sunucuda hem istemcide render edilen her tarih için `timeZone` parametresini her zaman açıkça iletin. Saat dilimi belirtilmemiş bir tarih iki farklı değere sahip bir tarihtir.
+
+## Para birimi bir dile değil, para birimi koduna ihtiyaç duyar
+
+Dil ve para birimi bağımsız kavramlardır. `fr-FR` otomatik olarak euro anlamına gelmez: Fransa'daki bir kullanıcı USD faturasına bakıyor olabilir.
+
+```ts
+new Intl.NumberFormat("fr-FR", { style: "currency", currency: "USD" }).format(
+  1234.5
+);
+// "1 234,50 $US"
+```
+
+Dil ayırıcıları, basamak gruplamasını ve simge yerleşimini yönetir. Para birimi ise verilerinizden gelir. Birini diğerinden çıkarmak muhasebe hatalarına yol açar.
+
+Ayrıca `currencyDisplay` seçeneğine dikkat edin. Dolar simgesini paylaşan birden fazla para biriminin bulunduğu arayüzlerde `"code"` seçeneği ABD, Kanada ve Avustralya dolarları arasındaki belirsizliği ortadan kaldırır.
+
+## Göreceli zaman mutlak zamandan daha kolay okunur
+
+Yakın zamandaki olaylar için "2 saat önce" ifadesi sabit bir zaman damgasından çok daha etkilidir ve `Intl.RelativeTimeFormat` bunu doğal bir şekilde yerelleştirir.
+
+```ts
+new Intl.RelativeTimeFormat("tr", { numeric: "auto" }).format(-1, "day");
+// "dün"
+```
+
+`numeric: "auto"`, "1 gün önce" yerine "dün" ifadesini üreten ayardır.
+
+## Intlayer Neler Ekler?
+
+Intlayer bu API'leri önbellekli yardımcı fonksiyonlarla sarar, böylece yukarıdaki Map önbelleğini kendiniz yönetmek zorunda kalmazsınız ve aktif dil her çağrıda iletilmek yerine varsayılan olarak uygulanır.
+
+```ts
+import {
+  number,
+  currency,
+  date,
+  relativeTime,
+  units,
+  compact,
+  list,
+} from "intlayer";
+
+number(1234.5); // "1.234,5"
+currency(1234.5, { currency: "EUR" }); // "1.234,50 €"
+date(new Date(), "short");
+relativeTime(now, twoHoursAgo, { unit: "hour", numeric: "auto" }); // "2 saat önce"
+units(5, { unit: "kilometer", unitDisplay: "long" }); // "5 kilometre"
+compact(1200); // "1,2 B"
+list(["elma", "muz", "portakal"]); // "elma, muz ve portakal"
+```
+
+`date()` fonksiyonu hazır ayarları da kabul eder (`"short"`, `"long"`, `"dateOnly"`, `"timeOnly"`, `"full"`). React ve Vue karşılıkları hook ve composable olarak mevcuttur ve aktif dili doğrudan bağlamdan çözer.
+
+Platform API'si üzerinde bir önbellekleme ve dil varsayılanı katmanıdır; asıl formatlama mantığı tamamen `Intl` tarafından yürütülür. Ayrıntılı imzalar [formatlayıcı dokümantasyonunda](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/formatters.md).
+
+## Sık yapılan hatalar
+
+- **Dil belirtilmeden `toLocaleDateString()` çağırmak.** Sunucudaki kapsayıcı ayarlarına bağlı olan varsayılan dili kullanır.
+- **Döngü içinde önbelleksiz formatlama.** Formatlayıcının oluşturulması maliyetin çoğunu oluşturur.
+- **İzomorfik tarihlerde `timeZone` belirtmemek.** Yerelde asla tekrarlanamayan hidrasyon hatası üretir.
+- **Dilden para birimi türetmek.** `fr-FR` her zaman euro demek değildir.
+- **Kullanıcıya gösterilen metinlerde düz `sort()` kullanmak.** Her zaman `Intl.Collator` kullanın.
+- **Ay veya gün adlarını koda gömmek.** Bunlar zaten her dil için CLDR içinde mevcuttur.
+- **Göreceli zamanda `numeric: "always"` bırakmak.** Her dilde "dün" sözcüğü varken "1 gün önce" sonucunu üretir.
+
+## İleri okuma
+
+- [Formatlayıcılar ve dil yardımcıları: `number`, `currency`, `date`, `relativeTime`, `list`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/formatters.md)
+- [Yapılandırma referansı](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/configuration.md)
+- [Frameworkler arası kıyaslama raporları](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/benchmark/index.md)
+- [react-intl uyumluluk adaptörü](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/react-intl.md)
+- [ICU mesaj formatı: çoğullar, select ve sayı iskeletleri](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/icu_message_format.md)
+- [Formatlayıcı ve çoğul kapsamı dahil çevirileri test etme](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/i18n_testing_strategies.md)
+- [Uluslararasılaştırmanın gerçekte neleri kapsadığı](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/what_is_internationalization.md)

package/blog/tr/detecting_missing_translations.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Kullanıcılarınızdan Önce Eksik Çevirileri Tespit Etme Yöntemleri"
+description: Eksik çeviriler sessizce hata verir. Geri dönüş mekanizmasının (fallback) bunları neden gizlediğini, gerçekten işe yarayan dört tespit katmanını ve çevrilmemiş anahtarlarda derlemeyi nasıl durduracağınızı öğrenin.
+keywords:
+  - eksik çevirileri bul
+  - eksik çeviri anahtarları
+  - i18n denetimi
+  - çevrilmemiş metinler
+  - çeviri kapsamı
+  - i18n lint
+slugs:
+  - blog
+  - detecting-missing-translations
+author: aymericzip
+---
+
+# Kullanıcılarınızdan Önce Eksik Çevirileri Tespit Etme Yöntemleri
+
+Eksik bir çeviri neredeyse hiçbir zaman bir istisna fırlatmaz. Kurulumunuza bağlı olarak ya Japon bir kullanıcıya İngilizce metni gösterir ya da canlı sayfada `checkout.summary.total` yazdırır. Her ikisi de yayına alınır, kod incelemesinden sorunsuz geçer ve sizin yerinize bir müşteri tarafından fark edilir.
+
+## İçindekiler
+
+<TOC/>
+
+## Hangi kütüphaneyi kullanırsanız kullanın geçerlidir
+
+Buradaki hiçbir şey tek bir yığına özgü değildir. Aşağıdaki tespit katmanları i18next, react-i18next, next-intl, react-intl, vue-i18n, next-translate veya Lingui üzerinde aynı şekilde çalışır, çünkü hepsi anahtarları aynı mantıkla çözer ve aynı şekilde hata verir.
+
+Araçlar da taşınabilirdir. Mesajlarınız bugün JSON kataloglarında duruyorsa, [Sync JSON eklentisi](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/plugins/sync-json.md) Intlayer'ı bu dosyalara yönlendirir, böylece içeriğinizi taşımadan veya tek bir import değiştirmeden denetim, doldurma ve test komutlarını kullanabilirsiniz:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // veya next-intl / react-intl için "icu"
+    }),
+  ],
+};
+
+export default config;
+```
+
+Çalışma zamanı API'sinin de aynı kalmasını istiyorsanız, [uyumluluk adaptörleri](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/index.md) paketleyici düzeyinde `useTranslation`, `$t` ve türevlerini takma adlandırır. Her halükarda, aşağıdaki komutları bir zorunluluk olarak değil, fikrin somut bir uygulaması olarak değerlendirin.
+
+## Neden görünmezdirler?
+
+Her i18n kütüphanesi bir anahtarı aynı zincirle çözer: aktif dili ara, varsayılan dile geri dön (fallback) ve bu da başarısız olursa anahtarın kendisini döndür. İşte bu son adım asıl sorundur. Bir hata oluşmaz, canlı ortamda uyarı verilmez ve hiçbir test başarısız olmaz; çünkü ardışık düzendeki hiçbir mekanizma eksik bir anahtarı anormal olarak değerlendirmez.
+
+Geri dönüş mekanizması durumu düzeltmek yerine daha da kötüleştirir. Sessizce İngilizce render edilen bir sayfa, İngilizce konuşan bir geliştiriciye ve otomatik kontrollerinize tamamen sorunsuz görünür. Hata yalnızca sonucu okuyamayan kişiye görünür.
+
+Bu nedenle soru "çalışma anında eksik çevirileri nasıl yönetirim" değil, "eksik bir çevirinin birleştirilmesini (merge) nasıl imkansız hale getiririm" olmalıdır.
+
+## Bunları yakalayabileceğiniz dört katman
+
+Her katman diğerlerinin gözden kaçırdığı bir şeyi yakalar. Birden fazlasına ihtiyacınız vardır.
+
+| Katman          | Yakaladıkları                                    | Kaçırdıkları                                    |
+| :-------------- | :----------------------------------------------- | :---------------------------------------------- |
+| Tipler (Types)  | Hiç var olmayan anahtarlar                       | Var olan ancak `ja` dilinde çevrilmemiş anahtar |
+| Linter          | Çeviriye hiç gönderilmemiş sabit dizeler         | Bir katalogdan eksik olan anahtarlar            |
+| Denetim (Audit) | Tanımlanmış her anahtardaki dil kapsamı          | Hiç çevrilebilir hale getirilmemiş metinler     |
+| Render testleri | Çözümlenen ancak yanlış render edilen anahtarlar | Test kapsamına alınmamış tüm sayfalar           |
+
+Çoğu ekibin yaşadığı açık üçüncü satırdır: anahtarlarının geçerli olduğunu bilirler, ancak on sekiz dilin tamamının gerçekten bir değere sahip olup olmadığını hiçbir şey denetlemez.
+
+## Katman 1: Anahtarı bir dize değil, bir tip yapın
+
+`t("checkout.summry.total")` derlenen bir yazım hatasıdır. Anahtarlarınız düz dizelerse, her yeniden adlandırma canlı ortam için bir risk ve her silme işlemi yetim bir anahtar bırakır.
+
+Tiplere ayrılmış anahtarlar bunu bir derleme hatasına dönüştürür. `react-i18next` bunu declaration merging ile destekler, `next-intl` mesaj yapınızdan çıkarım yapar, Lingui kaynak metinden ID'ler türetir ve Intlayer bildirim dosyalarından sıkı tipler üretir. Hepsi işe yarar; farklı olan ne kadar yapılandırma kodu yazmanız gerektiğidir.
+
+Bu katman gereklidir ancak yeterli değildir. Tipler varsayılan kataloğunuzun yapısını açıklar. Korecede bu anahtar için bir değer olup olmadığı hakkında hiçbir şey söylemezler.
+
+## Katman 2: Hiç anahtar olmamış dizeleri denetleyin (Lint)
+
+Bulamadığınız çeviri genellikle hiç dışa aktarılmamış olandır. Bir bileşene sabit kodlanmış bir etiket, katalog tabanlı her denetim için görünmezdir; çünkü araçlar açısından o dize mevcut değildir.
+
+Intlayer'ın ESLint eklentisi bunu `no-raw-text` ile ve ters durum için `no-unused-content` ile karşılar: bildirilmiş ancak artık hiçbir şey tarafından okunmayan içerik.
+
+```js fileName="eslint.config.mjs"
+import intlayer from "@intlayer/eslint-plugin";
+
+export default [
+  intlayer.configs.recommended,
+  {
+    rules: {
+      "@intlayer/no-raw-text": "error",
+      "@intlayer/no-unused-content": "warn",
+    },
+  },
+];
+```
+
+`no-unused-content`, katalogların sonsuza kadar büyümesini engelleyen kuraldır. Kullanılmayan anahtarlar bir doğruluk hatası değildir, ancak çeviri faturasını gereksiz yere artıran şeydir. Kuralların tam listesi [ESLint eklenti dokümantasyonunda](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/eslint.md).
+
+## Katman 3: Dil kapsamını denetleyin (Audit)
+
+Asıl soruya cevap veren katman budur. Intlayer bunu bir CLI komutu olarak sunar:
+
+```bash packageManager="npm"
+npx intlayer content test
+```
+
+Yapılandırılmış dillerinizi ve tanımlı sözlüklerinizi okur, ardından hangi anahtarların hangi dillerde ve hangi dosyada eksik olduğunu raporlar.
+
+Bunu herhangi bir yere bağlamadan önce bilmeye değer bir ayrıntı: **CLI bir rapor yazdırır ancak başarısızlık durumunda sıfır olmayan bir kodla çıkmaz.** Kırmızı bir derleme bekleyerek bunu bir ardışık düzene eklerseniz, kimsenin okumadığı bir metin yığınıyla birlikte yeşil bir derleme alırsınız. Derlemeyi durdurmak için aşağıda ele alınan programatik API'yi kullanın.
+
+## Katman 4: Test paketinde bunu doğrulayın (Assert)
+
+`listMissingTranslations()` size aynı denetimi veri olarak verir, bu da bir derleme kapısı (build gate) için tam olarak istediğiniz şeydir.
+
+```ts fileName="i18n.test.ts"
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("translations", () => {
+  it("has no missing required locales", async () => {
+    const result = await listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Üç alan döner ve aralarındaki ayrım önemlidir:
+
+- `missingTranslations`: anahtar başına, hangi dillerin ve hangi dosyadan eksik olduğu. Test başarısız olduğunda yazdıracağınız şey budur.
+- `missingLocales`: her anahtardaki eksik dillerin birleşimi.
+- `missingRequiredLocales`: yapılandırmanızdaki `requiredLocales` ile sınırlı eksikler (veya ayarlamadıysanız tüm diller).
+
+## `requiredLocales` kapıyı uygulanabilir kılan ayardır
+
+On sekiz dilde yayın yapmak, dağıtım gerçekleştirmek için on sekiz dilin tümünün tamamlanması gerektiği anlamına gelmez. Çoğu ekipte yayını engelleyen bir katman ve kademeli tamamlanan bir katman bulunur.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.FRENCH,
+      Locales.JAPANESE,
+      Locales.POLISH,
+    ],
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+`requiredLocales` olmadan, tanımlanan her dil zorunlu hale gelir ve son dil gelene kadar derlemeniz kırmızı kalır. Bu durum genellikle ekiplerin kontrolü tamamen devre dışı bırakmasına yol açar, bu da kontrole hiç sahip olmamaktan daha kötüdür.
+
+## Canlı ortamda bulunan eksikleri yakalamak
+
+Yukarıdaki katmanlar yeni boşlukları önler. Halihazırda yayında olan bir uygulama için iki yöntem işe yarar.
+
+**Sahte yerelleştirme (Pseudolocalization).** Her dizenin dönüştürüldüğü bir test dili çalıştırın; örneğin `[!!! Ĉĥéçķöũţ !!!]`. Halen düz İngilizce görünen her metin doğrudan koda gömülüdür. Katalog yerine render edilmiş sayfayı test ettiğinden, katalog denetiminin yapısal olarak göremediği şeyleri on dakikada bulur.
+
+**Kendi sitenizi tarayın.** Dile özgü URL'ler kullanıyorsanız, dil başına bir örnek çekin ve HTML içinde varsayılan dil dizelerinizi arayın. `/ja/` altında "Add to cart" içeren bir sayfa ya eksik bir çeviridir ya da farkında olmadığınız bir geri dönüştür (fallback).
+
+```bash
+curl -s https://example.com/ja/checkout | grep -c "Add to cart"
+```
+
+## Boşlukları doldurmak
+
+Neyin eksik olduğunu bildikten sonra `intlayer fill` boş girişleri doldurur ve `autoFill` seçeneği içerik tanımlandıkça dil başına dosyalar oluşturabilir. Bkz. [autoFill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/autoFill.md).
+
+Bu konuda net olmak gerekir: makineyle doldurulan çeviriler _görünür_ bir boşluğu _görünmez_ bir boşluğa dönüştürür. Anahtar artık bir değere sahiptir, denetim yeşile döner, ancak metni kimse okumamıştır. Bunu yayını açmak için bir iskele olarak kullanın, ardından bir müşterinin karar vermeden önce okuduğu kritik metinleri mutlaka bir insana yönlendirin.
+
+## Sık yapılan hatalar
+
+- **Geri dönüşü (fallback) bir güvenlik özelliği sanmak.** Bu bir acil durum render stratejisidir, güvenlik ağı değildir. Sessizce İngilizce çıkan bir sayfa hata bildirmeyen bir kusurdur.
+- **CI'ı durdurmak için CLI raporuna güvenmek.** `intlayer content test` sıfır koduyla çıkar. Bir test içinde assertion kullanın.
+- **Her dili zorunlu kılmak.** Bir sürüm yarım kalmış bir dil nedeniyle ilk kez engellendiğinde kontrol tamamen kaldırılır.
+- **Katalogları denetleyip render edilen sayfayı hiç incelememek.** Sabit kodlanmış dizeler tanım gereği katalog denetiminde görünmezdir.
+- **Testlerde yalnızca varsayılan dili kontrol etmek.** Asla eksik olamayacak tek dil odur.
+- **Makine dolgusunun döngüyü kapatmasına izin vermek.** Yeşil denetim, incelenmemiş metinler.
+
+## İleri okuma
+
+- [İçeriğinizi test etme: CLI denetimi, programatik API ve UI doğrulamaları](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/testing.md)
+- [ESLint eklenti kuralları (`no-raw-text` ve `no-unused-content` dahil)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/eslint.md)
+- [autoFill: dil başına bildirim dosyaları oluşturma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/autoFill.md)
+- [Yapılandırma referansı: `locales`, `requiredLocales`, `defaultLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/configuration.md)
+- [Frameworkler arası benchmark raporları](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/benchmark/index.md)
+- [i18next uyumluluk adaptörü](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/i18next.md)
+- [Uluslararasılaştırmanın gerçekten neleri kapsadığı](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/what_is_internationalization.md)
+- [Bileşen bazlı ve merkezi i18n karşılaştırması](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/per-component_vs_centralized_i18n.md)

package/blog/tr/i18n_in_ci_cd_pipelines.md

@@ -0,0 +1,247 @@
+---
+createdAt: 2026-09-02
+updatedAt: 2026-09-02
+title: "Hatalı Metinler Göndermeden CI/CD'de Çevirileri Otomatikleştirmek"
+description: i18n'i otomatikleştirebileceğiniz üç yer, pre-push, pull request ve çalışma zamanı. Bir derlemeyi kapsam üzerinden nasıl denetleyeceğinizi, güvenle otomatik dolduracağınızı ve sonsuz CI döngülerinden nasıl kaçınacağınızı öğrenin.
+keywords:
+  - çevirileri otomatikleştir ci
+  - i18n ci cd
+  - github actions çevirileri
+  - husky pre-push
+  - sürekli yerelleştirme
+  - çeviri ardışık düzeni
+slugs:
+  - blog
+  - i18n-in-ci-cd-pipelines
+author: aymericzip
+---
+
+# Hatalı Metinler Göndermeden CI/CD'de Çevirileri Otomatikleştirmek
+
+Manuel çeviri, hızlı sürüm döngülerine ayak uyduramaz. Biri Cuma günü yeni bir metin ekler, dışa aktarma bir sonraki sprinte kalır ve o zamana kadar üç dil daha geride kalır. Çeviriyi otomatikleştirmek kolaydır. Ancak kontrol edilmemiş makine çıktılarını kullanıcılara sessizce sunmadan otomatikleştirmek asıl düşünülmesi gereken kısımdır.
+
+## İçindekiler
+
+<TOC/>
+
+## Otomatikleştirmek için geçiş (migrasyon) yapmanıza gerek yok
+
+Aşağıdaki ardışık düzen yapıları kütüphaneden bağımsızdır, araçlar da öyledir. Mesajlarınız i18next, next-intl, react-intl, vue-i18n veya next-translate için JSON kataloglarıysa, [Sync JSON eklentisi](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/plugins/sync-json.md) bu dosyaları doğrudan yerinde okur ve yazar:
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config = {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "i18next", // veya next-intl / react-intl için "icu"
+    }),
+  ],
+};
+
+export default config;
+```
+
+Uygulamanız her zamanki gibi içe aktarmaya devam eder. Aşağıdaki CI işleri mevcut kataloglarınızı doldurur ve denetler; incelemecinin gördüğü fark, büyük bir kod taşıma işlemi değil, `locales/fr/checkout.json` dosyasındaki bir değişikliktir. gettext iş akışları için bir [Sync PO eklentisi](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/plugins/sync-po.md) ve çalışma zamanı API'nizin değişmeden kalmasını istiyorsanız [uyumluluk adaptörleri](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/index.md) de mevcuttur.
+
+## Kapıyı (Gate) doldurmadan (Fill) ayırın
+
+İki farklı görev sürekli olarak birbirine karıştırılır.
+
+Bir **kapı (Gate)**, başarısız olan bir kontroldür. Gerekli diller eksik olduğu için bu derlemenin yayınlanmaması gerektiğini söyler. Hiçbir şey yazmaz.
+
+Bir **doldurma (Fill)**, bir mutasyondur. Eksik çevirileri oluşturur ve bunları commit eder. Bir derlemeyi asla başarısız kılmaz.
+
+Yalnızca doldurma çalıştırmak hiçbir şeyin engellenmediği ve gözden geçirilmemiş makine çıktısının doğrudan canlıya aktığı anlamına gelir. Yalnızca kapı çalıştırmak ise derlemenin kırmızıya dönmesi ve her seferinde bir insanın müdahale etmesi gerektiği anlamına gelir. Çoğu ekip, farklı tetikleyicilere bağlı her ikisini de ister: bir pull request üzerinde doldurma, sürüm dalına birleştirme sırasında kapı.
+
+## Otomasyon nerede konumlanabilir
+
+| Aşama            | Tetikleyici | Uygunluk                                      | Maliyet                                               |
+| :--------------- | :---------- | :-------------------------------------------- | :---------------------------------------------------- |
+| Pre-push kancası | Yerel git   | Hızlı geri bildirim, sıfır CI dakikası        | Geliştiricinin makinesinde ve API anahtarında çalışır |
+| Pull request     | CI işi      | Birleştirmeden önce inceleme, güvenli sırlar  | CI dakikaları ve PR başına model çağrıları            |
+| Sürüm dalı       | CI işi      | Kapsam üzerinde katı kapı denetimi            | Ucuz, model çağrısı yok                               |
+| Çalışma zamanı   | CMS         | Yeniden derleme yapmadan metin değişiklikleri | Barındırılan hizmet bağımlılığı                       |
+
+## Pre-push: En hızlı döngü
+
+Husky, kod makineden çıkmadan önce doldurmayı çalıştırır, böylece çeviriler bunlara ihtiyaç duyan dizelerle aynı push içinde yer alır.
+
+```bash fileName=".husky/pre-push"
+npx intlayer build
+npx intlayer fill --unpushed --mode complete
+```
+
+`--unpushed`, çalışmayı henüz push edilmemiş içerikle sınırlar, bu da her push işleminde dakikalarca beklemeyi önler. `--mode complete`, zaten bir değere sahip olan girişleri yeniden yazmadan eksik olanları doldurur, böylece incelenmiş bir çeviri asla sessizce değiştirilmez.
+
+Bir monorepo için her uygulamanın kapsamını belirleyin:
+
+```bash fileName=".husky/pre-push"
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
+```
+
+Dezavantaj gerçektir: her geliştiricinin bir API anahtarına ihtiyacı vardır ve maliyet push yapan kişiye biner. Bu yüzden ekipler büyüdükçe bu süreci CI ortamına taşır.
+
+## Pull request: İncelemenin yapıldığı yerde doldurun
+
+Aynı iş GitHub Actions içinde, yalnızca diff kapsamına alınmış olarak:
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm install
+      - run: npx intlayer build
+      - run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+      - name: Commit
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git config --local user.email "action@github.com"
+            git config --local user.name "GitHub Action"
+            git add .
+            git commit -m "chore: auto-fill missing translations [skip ci]"
+            git push origin HEAD:${{ github.head_ref }}
+          fi
+```
+
+Burada dört ayrıntı hayati önem taşır:
+
+- **`fetch-depth: 0`**, `--git-diff`'in çalışması için gereklidir. Sığ bir klonun (shallow clone) diff yapabileceği bir tabanı yoktur ve işlem sessizce hiçbir şeyi kapsamaz.
+- **Commit mesajındaki `[skip ci]`**, iş akışının kendini sonsuz döngüde yeniden tetiklemesini engeller. Bu olmadan iş bir commit yapar, bu yeni bir çalıştırma açar, o da tekrar commit yapar ve CI bütçesini tüketir.
+- **`cancel-in-progress` ile `concurrency`**, iki eşzamanlı push işleminin aynı dosyaları yazmak için yarışmasını durdurur.
+- **`--git-diff`**, doldurmayı PR'da nelerin değiştiğiyle sınırlar. Bunu atlarsanız her çalıştırmada tüm kataloğu yeniden çevirirsiniz.
+
+Çeviriler PR dalında bir commit olarak görünür, bu da bir incelemecinin bunları diff içinde görebileceği anlamına gelir. Bunu birleştirmeden sonra değil burada yapmanın temel nedeni budur.
+
+## Sürüm dalı: Kapı (Gate)
+
+Kapının model erişimine ihtiyacı yoktur ve hızlı olmalıdır.
+
+```yaml fileName=".github/workflows/ci.yml"
+- run: npm run test:i18n
+```
+
+CLI raporundan ziyade kapsamı doğrulayan bir test ile desteklenir:
+
+```ts fileName="i18n.test.ts"
+import { listMissingTranslations } from "intlayer/cli";
+
+test("has no missing required locales", async () => {
+  const result = await listMissingTranslations();
+  if (result.missingRequiredLocales.length > 0) {
+    console.log(result.missingTranslations);
+  }
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+`npx intlayer content test` bir rapor yazdırır ancak sıfır koduyla çıkar, bu nedenle bilgilendirir fakat derlemeyi engellemez. Yerel olarak bunu kullanın; CI ortamında ise assertion testini kullanın. [Eksik çevirileri tespit etme](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/detecting_missing_translations.md) bölümünde daha fazlası bulunmaktadır.
+
+## `requiredLocales`, kapıyı sürdürülebilir kılan unsurdur
+
+On sekiz dilin tamamını talep eden bir kapı, en yavaş dil tamamlanana kadar her sürümü engeller ve bir ay içinde devre dışı bırakılır.
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+Hizmet verdiğiniz dilleri tanımlayın, bir sürümü engellemesi gerekenleri zorunlu tutun. Geri kalanı eşzamansız olarak doldurulur ve asla bir dağıtımı geciktirmez.
+
+## Çevirileri tamamen depodan (repo) çıkarmak
+
+Diğer model, kodda tek bir dil tanımlamak ve geri kalanını Live Sync özellikli CMS aracılığıyla uzaktan yönetmektir. İçerik değişiklikleri daha sonra hiçbir yeniden derleme gerektirmez, bu da metin düzenleme hızını kod dağıtım hızından ayırır.
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+};
+
+export default config;
+```
+
+Bu, geliştirici olmayan ekiplerin içeriğe sahip olduğu durumlar için uygundur. Bu bir ödünleşimdir: editör özerkliği kazanırsınız ve git checkout'un uygulamanın neyi render ettiğini tam olarak tanımlaması özelliğini kaybedersiniz. Ayrıntılar [CMS dokümantasyonunda](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/intlayer_CMS.md).
+
+`clientSecret`'ın sunucu tarafı bir kimlik bilgisi olduğunu unutmayın. CI sırlarında ve sunucu ortamınızda bulunmalıdır, istemci paketine ulaşan hiçbir şeyde yer almamalıdır.
+
+## Dürüst sınırlama
+
+Yukarıdaki her şey _kapsamı_ otomatikleştirir, _kaliteyi_ değil. Bir makine doldurması görünür bir boşluğu görünmez bir boşluğa dönüştürür: anahtar artık bir değere sahip olduğu için denetim yeşile döner, ancak metni kimse okumamıştır.
+
+Bu bir dahili araç, değişiklik günlüğü veya beta diller için kabul edilebilir. Fiyatlandırma, yasal metinler, ödeme hatası mesajları veya müşterinin karar vermeden önce okuduğu herhangi bir metin için kabul edilemez. Bunları bir insana yönlendirin ve incelenmiş bir dizenin sonraki bir çalıştırmayla asla üzerine yazılmaması için her yerde `--mode complete` kullanın.
+
+Çıktısının en azından tutarlı olması için modele bağlam verin:
+
+```ts
+ai: {
+  applicationContext: "B2B faturalandırma uygulaması. Resmi dil. Ürün adını asla çevirmeyin.",
+}
+```
+
+## Sık yapılan hatalar
+
+- **Otomatik commit'te `[skip ci]` olmaması.** İş akışı döngü içinde kendini sürekli tetikler.
+- **`--git-diff` ile sığ klon (shallow clone).** Karşılaştırılacak taban olmadığından hiçbir şey doldurulmaz ve hata verilmez.
+- **Her çalıştırmada tüm kataloğu doldurmak.** Faturaları kontrol altında tutmak için `--git-diff` veya `--unpushed` ile sınırlandırın.
+- **CLI raporunu kapı olarak kullanmak.** Sıfır koduyla çıkar.
+- **Her dili zorunlu kılmak.** Bir sürümü ilk engellediğinde kapı kaldırılır.
+- **Hiçbir kapısı olmayan bir doldurma işi.** Hiçbir şey başarısız olmaz, böylece makine kopyası incelenmeden canlıya ulaşır.
+- **Depoda model API anahtarları.** `clientSecret` gibi onlar da CI sırlarında yer almalıdır.
+
+## İleri okuma
+
+- [CI/CD: Husky, GitHub Actions ve CMS ile çevirileri otomatik oluşturma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/CI_CD.md)
+- [İçeriğinizi test etme ve kapsam üzerinden derlemeyi denetleme](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/testing.md)
+- [autoFill: dil başına bildirim dosyaları oluşturma](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/autoFill.md)
+- [Yapılandırma referansı: `locales`, `requiredLocales`, `editor`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/configuration.md)
+- [Frameworkler arası karşılaştırmalı değerlendirme raporları](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/benchmark/index.md)
+- [i18next uyumluluk adaptörü](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/compat/i18next.md)
+- [Eksik çevirileri tespit etme](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/detecting_missing_translations.md)
+- [Kırılgan testler yazmadan çevirileri test etme](https://github.com/aymericzip/intlayer/blob/main/docs/blog/tr/i18n_testing_strategies.md)