Çok dilli metin ve alignment mimarisi

Çok dillilik katmanı, her dildeki metni bağımsız ve exact bir sürüm olarak korur; iki sürüm arasındaki karşılıkları ayrıca alignment annotation’ı olarak tutar. Alignment kayıtlarının tamamı silinse bile Türkçe ve hedef dil metinleri kendi kaynak byte’larından reconstruct edilebilmelidir.

Normatif model ADR-008’de, core ile annotation sınırı ADR-001’de ve kimlik düzeltme kuralları ADR-002’de tanımlanır. Bu rehber, kabul edilmiş F7 uygulamasının mevcut sınırlarını ve yeni bir dil eklemek için izlenecek operasyonel sırayı açıklar.

Zihinsel model

flowchart LR
  accTitle: Çok dilli metin ve alignment authority akışı
  accDescr: Bağımsız source ve target text release seçimleri aday alignment gruplarına, insan review kararlarına, iki taraflı coverage doğrulamasına ve private reader release'ine bağlanır.
  source[source text release] --> sourceUnit[source units]
  target[target text release] --> targetUnit[target units]
  profile[alignment profile] --> scope[alignment scope]
  sourceUnit --> scope
  targetUnit --> scope
  scope --> candidate[candidate groups]
  candidate --> review[review decisions]
  review --> group[effective groups]
  group --> order[source ve target order]
  order --> coverage[coverage closure]
  coverage --> release[alignment release]
  release --> reader[private reader]
  release -. kapalı policy .-> route[derived reference route]

Bu akış dört authority türünü özellikle ayırır:

Authority	Ne söyler?	Ne söylemez?
Exact text	Bir dil sürümünde yayımlanan karakterler ve sıraları	Başka dildeki karşılığı
Candidate evidence	Hangi seçimlerin eşleşebileceği	Eşleşmenin kabul edildiği
Review ve alignment release	Hangi ordered unit grubunun geçerli correspondence olduğu	Çevirinin edebî kalitesi veya kelime kelime eşdeğerlik
Reader projection	Seçilen release ve sırada ne gösterileceği	Public API veya otomatik atıf yetkisi

Confidence yalnız review önceliğidir. Metin benzerliği, aynı satır sayısı, normalize metin veya yüksek confidence bir adayı accepted yapamaz.

Kimlikler ve ilişkiler

Model tek bir Türkçe cümleye tek bir hedef string bağlamaz. Temel kimlikler şunlardır:

Kayıt	Kimlik taşıyan gerçek
text_version / text_release	Dil, edisyon ve immutable exact metin sürümü
alignment_profile	Unitization, scope, coverage ve order kuralları
alignment_unit	Tek bir text release içindeki exact sentence/span seçimi
alignment_scope	İki release ve iki exact kapsam arasında değerlendirilen evren
alignment_candidate	Bir run’ın ürettiği exact ordered üyeliğe sahip öneri
alignment_group	Review ile kabul edilmiş tek bipartite correspondence/disposition
alignment_order	Bir scope tarafındaki effective grupların tek tam sırası
alignment_release	Group, order, accepted/unresolved partition ve provenance kökleri
propagation_policy	Atıfın başka sürümde nasıl türetilmiş rota arayabileceği

Bir group, source ve target tarafında ordered üye listeleri taşır. 2:3 ilişki altı bağımsız pairwise edge değildir; ortak anlamı taşıyan tek gruptur.

Source	Target	Disposition / shape
1	1	correspondence / one_to_one
1	2 veya daha fazla	correspondence / split
2 veya daha fazla	1	correspondence / merge
2 veya daha fazla	2 veya daha fazla	correspondence / complex
1 veya daha fazla	0	source_only
0	1 veya daha fazla	target_only

source_only ve target_only, review edilmiş boş-taraf kararlarıdır. Henüz karşılığı bulunmamış unit aynı şey değildir; unresolved kalır.

Mevcut F7 uygulaması

ADR-008 bütün diller için genel logical modeldir. Bugünkü production-shaped pipeline ise kabul edilmiş rnk-en kaynağına özgüdür. Bu ayrım yeni bir dil eklerken korunmalıdır.

Katman	Bugünkü artifact	Durum ve sınır
İngilizce exact kaynak	data/translations/text/en-rnk-en-2026-v1	10 kitap ve 9.544.504 kaynak byte’ı exact korunur; alignment veya public reader değildir
Legacy alignment parse	alignments/en-rnk-en-v1/parsed	171 reviewed dosyanın fiziksel syntax ve byte koordinatlarını kayıpsız taşır; indentation semantik edge değildir
Candidate semantics	semantics/candidate-set	34.126 candidate group; tamamı başlangıçta öneri/evidence’dır
Türkçe crosswalk	turkish-crosswalk	Candidate source üyelerini 57.630 stable sentence occurrence ve exact supporting span evrenine bağlar
Review/confidence	review-confidence	33.911 promote, 215 needs_review; confidence review’dan bağımsızdır
Exact validation	validation	İki taraflı accepted/unresolved partition, content witness ve order evidence; overall durum partialdır
DB ve private reader	alignment_control + reader/catalog.json	Private publication yetkilidir; yalnız auditor bounded reader’ı çalıştırabilir
Atıf propagation	reference-propagation-v1.yml	İlk release’te otomatik propagation/publication/persistent derivation kapalıdır
İkinci dil kanıtı	ar-sample-v1	Türkçe-Arapça RTL test fixture’ı model genelliğini kanıtlar; gerçek çeviri veya publication değildir

Mevcut İngilizce release 171 scope içinde 33.911 accepted group taşır. 9.001 Türkçe unit, 9.026 İngilizce unit ve 215 candidate açıkça unresolved kalır; yalnız üç scope iki taraflı complete durumdadır. Bu nedenle release’in partial olması hata veya gizli boşluk değil, doğrulanmış mevcut durumdur. Ayrıca bulunan 88 order inversion henüz reorder-specific review almadığı için accepted reorder sayılmaz.

PostgreSQL authority ve reader

20260824090000_f7_010_multilingual_reader.sql private alignment_control schema’sını kurar. Fiziksel ilişkiler şu gruplardadır:

Amaç	Tablolar
Exact hedef kaynak	target_source_releases, target_source_books
Stable model	alignment_profiles, alignment_scopes, alignment_units, alignment_scope_units, alignment_candidates, alignment_candidate_members, alignment_groups, alignment_group_members
Release kararı	alignment_releases, alignment_release_scopes, alignment_release_candidates, alignment_release_scope_units, alignment_release_groups, alignment_orders, alignment_publications

Stable satırlar değişmeyen seçim ve üyelik kimliğini, release satırları ise belirli bir yayındaki review, membership, order ve publication durumunu taşır. Böylece successor release, byte-identical stable kimlikleri yeniden kullanabilir; önceki release’in kararlarını değiştirmez.

Private reader şu imzaya sahiptir:

select *
from alignment_control.list_multilingual_chapter_units_v1(
  p_alignment_release_id => '11111111-1111-1111-1111-111111111111',
  p_chapter_id => '22222222-2222-2222-2222-222222222222',
  p_order_side => 'source',
  p_after_position => null,
  p_after_item_id => null,
  p_limit => 50
);

p_order_side, Türkçe kaynak sırası ile hedef kitabın sırası arasında bilinçli seçimdir. Cursor (reader_position, reader_item_id) ikilisidir ve sayfa sınırı 1-100’dür. Çıktıdaki temel durumlar:

authority_status	mapping_status	Anlamı
accepted	mapped	Effective reviewed group; iki tarafın exact unit listeleri vardır
unresolved	unresolved_candidate	Candidate ve iki tarafı gösterilebilir; correspondence kabul edilmemiştir
unresolved	source_fallback	Türkçe unit vardır, accepted hedef karşılığı yoktur; Türkçe metin İngilizce diye sunulmaz
unresolved	target_only	Hedef unit vardır, accepted Türkçe karşılığı yoktur

Bu fonksiyon doğrudan PostgREST/public API değildir. Schema ve fonksiyonlar anon, authenticated ve app_runtime rollerine kapalıdır; yalnız auditor doğrudan execute hakkına sahiptir. F8 public katmanı bu yetki sınırını değiştirmez.

Public API ve release binding

F8-011, kabul edilmiş F7 alignment release’ini mevcut Türkçe reader deployment’ına api_control.multilingual_release_bindings ile bağlar. Binding şu kimlikleri tek bir immutable data release root altında sabitler:

• Türkçe core_release_id ve source_text_version_id
• F7 alignment_release_id ve hesaplanan publication root
• İngilizce target_source_release_id, target_text_version_id, dil ve script
• mevcut Osmanlıca, lexical, heading, note ve repetition publication kökleri

Hazırlama ve aktivasyon ayrı işlemlerdir:

select api_control.prepare_multilingual_release_v1(
  p_alignment_release_id => '5d2a4379-3acd-55e3-9583-2eb8619659f4',
  p_source_deployment_id => '<aktif-v1.7-deployment>'
);

select api_control.activate_multilingual_deployment_v1(
  p_release_manifest_id => '<hazirlanan-manifest>',
  p_expected_current_deployment_id => '<aktif-v1.7-deployment>'
);

Aktivasyon publication root’u ve iki text version bağını yeniden hesaplayıp doğrular. Alignment veya çeviri artifact’ı bu sırada yeniden üretilmez.

Public operasyon chapter ve hedef dil odaklıdır:

POST /rest/v1/rpc/list_chapter_alignment_units_v1
Content-Profile: api_v1

{
  "chapter_id": "...",
  "target_locale": "en",
  "order_side": "target",
  "cursor": null,
  "page_size": 100,
  "deployment_id": "..."
}

alignment_control.list_public_chapter_units_v1 security-definer projeksiyonu private reader’ı alignment owner yetkisiyle çağırır; application rollerine alignment_control kullanım veya tablo okuma hakkı verilmez. Public çıktı yalnız accepted group kimliğini ve exact source/target unit metinlerini taşır. Candidate kimliği, review evidence’ı, raw unresolved reason, source path ve byte koordinatları çıkmaz. Cursor deployment, operation, data root, chapter, locale, order side ve çağıran subject’e imzalı olarak bağlıdır.

Operasyon bir chapter scope yayımlanmamışsa unavailable döndürür. Yayımlanmış sayfada dört mapping durumu kapalı union olarak korunur. unresolved_candidate iki exact metni bağlam iddiası olmadan gösterebilir; source_fallback Türkçe kimliğini, target_only İngilizce kimliğini korur. Unitleri birleştirip tam İngilizce chapter reconstruction iddiası üretilmez.

Review ve yayın durumları

Bir alignment’ın yaşam döngüsünü şu sırayla okuyun:

1. Parser exact kaynak evidence’ını taşır.
2. Generator ordered source/target seçimleriyle candidate üretir.
3. Crosswalk her source seçimini stable Türkçe sentence/span kimliğine bağlar.
4. Review exact candidate bytes’ı için promote veya needs_review kararı verir.
5. Validator her iki unit evrenini accepted ve unresolved olarak gap-free böler.
6. Yalnız promoted candidate effective alignment_group olabilir.
7. Publication group, iki side order ve coverage köklerini atomik olarak kapatır.

high confidence taşıyan ama blocking finding’i olan candidate yine needs_reviewdır. MINOR_ISSUES document etiketi tekil finding’i kapatmaz. Benzer şekilde bir release partial iken accepted grupları güvenle okuyabilir; unresolved unitleri gizleyerek complete gibi sunamaz.

Group üyeleri, disposition veya boundary düzelirse yeni group kimliği ve supersession kaydı gerekir. Yalnız açıklama, confidence veya yeni evidence eklenmesi mevcut subject kimliğini değiştirmez. Source ya da target text release değişirse eski alignment tarihsel release’e bağlı kalır; successor metin için yeni scope/unit/group review’u yapılır.

Yeni dil ekleme akışı

Bugünkü İngilizce extractor ve crosswalk kodunu yalnız dosya adlarını değiştirerek genelleştirmeyin. Yeni bir production dili şu sırayla eklenir:

1. Kaynağı dondurun. Lisans, provenance, exact upstream sürüm ve dahil/hariç partition’ını kaydedin. Prompt cache, duplicate Türkçe ağaç ve geçici raporları release girdisi yapmayın.
2. Bağımsız exact text release üretin. Canonical BCP 47 language tag, script, direction, version/edition kimliği, exact UTF-8 bytes ve reconstruction witness tanımlayın. Türkçe ID’leri hedef dile vermeyin.
3. Profile ve scope tasarlayın. Dilin cümle/başlık yapısına uygun unitization, structural exclusion, iki taraflı kapsam ve order kurallarını sürümleyin. Hedef metni Türkçe cümle sayısına zorlamayın.
4. Candidate evidence üretin. 1:1, split, merge, complex ve boş-taraf önerilerini tek bipartite group payload’ı olarak saklayın. Normalize metni yalnız locator olarak kullanın; exact selection witness taşıyın.
5. Stable source crosswalk kurun. Her source üyesini mevcut Türkçe release’in sentence veya exact span kimliğine bağlayın. Eşleşmeyeni tahminle doldurmayın.
6. Semantik review yapın. Candidate bytes, disposition, sınırlar ve sıra birlikte incelenir. Confidence yalnız iş sırasını belirler.
7. Coverage ve order’ı kapatın. Her iki tarafta her in-scope unit tam bir kez accepted veya unresolved partition’a girmeli; reorder açıklaması ayrıca review edilmelidir.
8. Immutable release yayımlayın. Stable ve release-specific kayıtları transaction içinde doğrulayın; counts, roots, provenance closure ve publication kaydını birlikte kapatın.
9. Reader/API entegrasyonu ekleyin. Önce private bounded reader’ı, sonra F8 public envelope ve açık missing/fallback durumlarını uygulayın. Otomatik atıf propagation için mevcut policy’yi yerinde açmayın; yeni policy ve bağımsız review gerekir.

İkinci dil için gerçek kaynak şekli öğrenilmeden generic production importer yazmak erken soyutlamadır. Paylaşılması gereken kısım exact text, unit/group/order/coverage schema ve verifier sözleşmeleridir; source extraction adapter’ı dile ve upstream yapıya özgü kalabilir.

Odaklı doğrulama

Committed İngilizce artifact’larını değiştirmeden doğrulamak için:

ruby scripts/translations/english_text_source.rb --verify
ruby scripts/translations/alignment_parser.rb --verify
ruby scripts/translations/alignment_edges.rb --verify
ruby scripts/translations/turkish_crosswalk.rb --verify
ruby scripts/translations/alignment_review.rb --verify
ruby scripts/translations/alignment_validation.rb --verify
ruby scripts/translations/multilingual_reader.rb --verify
ruby scripts/translations/reference_propagation_policy.rb --verify

Modelin İngilizceye özgü olmadığını gösteren küçük RTL fixture için:

ruby -w tests/translations/multilingual_alignment_sample_test.rb
ruby scripts/translations/multilingual_alignment_sample.rb --verify

--verify mevcut committed output’u okur ve sözleşmeye göre denetler. --build ve --check-reproducible daha geniş üretim işlemleridir; yalnız ilgili source release ve packet kapsamı değiştiğinde çalıştırılır. Olağan doküman veya UI değişikliğinde legacy checkout, full corpus build ya da DB rebuild gerekmez.

Hata teşhisi

Belirti	Muhtemel anlam	Güvenli işlem
Exact byte/scalar witness uyuşmuyor	Source artifact veya selection boundary değişti	Eski release’i değiştirmeyin; kaynağı doğrulayın ve gerekiyorsa successor release üretin
Candidate yüksek confidence ama needs_review	Açık semantic finding veya contextual risk var	Confidence ile promote etmeyin; exact candidate için review tamamlayın
Scope partial	Accepted ve unresolved partition birlikte mevcut	Unresolved sayıları ve nedenleri gösterin; scope’u complete ilan etmeyin
source_fallback dönüyor	Accepted hedef counterpart yok	Kaynak metni açık fallback etiketiyle gösterin; hedef dil metni olarak persist etmeyin
Order inversion bulundu	İki taraftaki relative group sırası farklı	Exact inversion evidence’ını semantik olarak inceleyip açıklama ekleyin
App rolü reader fonksiyonuna erişemiyor	Private ACL doğru çalışıyor	auditor rolünü uygulamaya vermeyin; F8 public wrapper’ını kullanın
Bir atıf için hedef rota dönmüyor	İlk propagation policy bilinçli olarak kapalı	Authored target’ı koruyun; boş sonucu alignment eksikliğiyle karıştırmayın

Atıf sınırı

multilingual-reference-propagation-v1 bugün inerttir: automatic_propagation, automatic_publication ve persistent_reference_derivation değerleri falsedur. İstek sonucu not_evaluated, destination set ise boştur.

İleride bir atıf başka dilde sunulacaksa authored reference yine ilk hedefini korur. Alignment yalnız release ve policy kimliklerini taşıyan derived presentation route üretebilir. split, merge ve complex rotalarda destination cardinality korunur; bir unit içindeki daha dar seçim ayrıca review edilmedikçe exact hedef span diye gösterilmez. Pivot dil üzerinden transitive alignment da kendiliğinden direct edge oluşturamaz.

Değişiklik kontrol listesi

• Her dil sürümü alignment olmadan exact reconstruct ediliyor mu?
• Unit ve scope seçimleri exact release kimliği ve witness taşıyor mu?
• Many-to-many ilişki tek group olarak mı korunuyor?
• Accepted, unresolved, source-only ve target-only birbirinden ayrılıyor mu?
• Confidence ile review authority birbirine karışıyor mu?
• Source ve target order ayrı ve tam mı?
• Coverage iki tarafta gap-free partition mı?
• UI fallback hedef dil metni gibi mi davranıyor?
• Düzeltme historical ID’yi mutasyona uğratmak yerine successor üretiyor mu?
• Public reader yalnız F8 envelope üzerinden mi açılıyor?