neta/docs/self-hosted-redesign/i18n-phase-8.md

title, status, completed_at

title	status	completed_at
I18n Faz 8 — API v1 ve mobil hazırlık	completed	2026-07-19

I18n Faz 8 — API v1 ve mobil hazırlık

Bu fazda self-host instance içindeki dil modeli, gelecekteki React Native istemcilerinin güvenli şekilde keşfedebileceği bir API v1 sözleşmesine taşındı. Değişiklikler geriye uyumludur; mevcut v1 response alanları değiştirilmedi, sadece additive alanlar eklendi.

Tamamlananlar

• instance.localization capability kaydı eklendi.
• /.well-known/neta discovery document içine additive locale özeti eklendi.
• /api/v1/meta içinde localization contract genişletildi:
  • supportedLocales
  • fallbacks
  • catalogVersion
  • negotiator
  • responseContract
• /api/v1/me response'u kullanıcının dil bilgisini ayrı döner:
  • language
  • portalLocale
  • resolvedLocale
  • requestedLocale
  • source
  • fallbackChain
• Accept-Language parser ve locale negotiation helper'ı eklendi.
• Gelecek resource endpoint'leri için localized response contract'ı yazıldı.
• Owner mutation contract'ında translations shape'i standartlaştırıldı: Record<locale, Record<field, string | null>>.
• UNSUPPORTED_LOCALE hata kodu API response mapping'e eklendi.
• API hata response'larında client localization için messageKey kullanımı netleştirildi.
• tr, en, fr için contract fixture'ları eklendi.
• i18n:phase8-smoke mobile localization negotiation ve contract shape'lerini runtime olarak doğrulayacak şekilde eklendi.

Mobil istemci davranışı

Mobil istemci ilk açılışta /.well-known/neta endpoint'ine gider ve instance.localization capability'sini kontrol eder. Capability bilinmiyorsa istemci bunu fatal hata olarak ele almamalı; capability listesi additive olduğu için unknown capability değerleri yok sayılmalıdır.

Dil seçimi için önerilen sıra:

1. Kullanıcının explicit seçimi varsa /api/v1/me?locale=xx ile gönder.
2. Explicit seçim yoksa Accept-Language header'ını gönder.
3. Server /api/v1/me.data.localization.resolvedLocale değerini gerçek kaynak kabul et.

locale query param'ı aktif olmayan bir locale'e işaret ederse API UNSUPPORTED_LOCALE döner. Accept-Language içinde desteklenmeyen değer varsa server sessizce instance default locale'e düşebilir.

Hata response'larında kullanıcıya gösterilecek metin mobile client tarafından locale'e göre çözülmelidir. Server bu amaçla error.details.messageKey alanını döndürür:

{
  "ok": false,
  "error": {
    "code": "UNSUPPORTED_LOCALE",
    "message": "Unsupported locale.",
    "details": {
      "messageKey": "validation.unsupportedLocale",
      "requestedLocale": "fr"
    }
  }
}

Resource response contract

Gelecek /api/v1/projects, /api/v1/tasks, /api/v1/clients gibi resource endpoint'leri şu shape'i kullanmalı:

{
  resource: TResource;
  localized: TResource;
  locale: string;
  fallbackChain: string[];
}

Bu contract sayesinde mobil taraf original kaydı ve locale çözülmüş kaydı aynı anda taşıyabilir.

Mutation translations contract

Owner/freelancer mutation endpoint'leri çok dilli alanları şu shape ile kabul etmeli:

{
  translations: {
    tr: { name: "Marka sitesi", description: "..." },
    en: { name: "Brand website", description: "..." },
    fr: { name: "Site de marque", description: "..." }
  }
}

Server sadece authorized owner mutation'larında bu alanı kabul eder. Müşteri portal oturumu translations mutation contract'ını kullanamaz; portal locale yalnızca kendi okuma response'unu etkiler.

Cache ve URL notları

• /.well-known/neta ve /api/v1/meta public cache kullanır.
• Metadata içindeki URL'ler APP_URL üzerinden absolute üretilir.
• Locale catalog değişikliklerinde catalogVersion artacağı için mobil istemci meta cache'ini güvenli şekilde invalidate edebilir.

Fixture'lar

• docs/self-hosted-redesign/i18n-phase-8-fixtures/api-v1-locale-tr.json
• docs/self-hosted-redesign/i18n-phase-8-fixtures/api-v1-locale-en.json
• docs/self-hosted-redesign/i18n-phase-8-fixtures/api-v1-locale-fr.json

Verification

Çalıştırılan komutlar:

pnpm i18n:phase8-smoke
pnpm typecheck
pnpm build
pnpm phase9:smoke
git diff --check