Büyük uygulamalar için pratik Vue 3 i18n iş akışı: anahtar adlandırma, çoğullar, QA kontrolleri ve prodüksiyonda eksik çevirilerden kaçınmak için yayın adımları.
Uygulamanız birkaç yüz stringi geçtiğinde ilk bozulan şey genellikle Vue I18n olmaz. Tutarlılıktır. İnsanlar anahtarları farklı stillerde ekler, aynı fikri farklı isimlerle çoğaltır ve kim mesajların güvenle silinebileceğinden emin değildir.
Eksik çeviriler de nadir olmaktan çıkar. Normal kullanıcı yollarında, özellikle daha az kullanılan ekranlarda (ayarlar, hata durumları, boş durumlar ve bildirimler) ortaya çıkarlar.
Bir çeviri eksik olduğunda kullanıcılar genellikle üç hatadan birini görür: boş bir arayüz (etiketsiz bir buton), ham anahtarlar (örneğin checkout.pay_now) veya sayfanın bir kısmının dil değiştirdiği garip bir geri dönüş davranışı. Bu üçü de küçük bir hata gibi hissettirmez. Uygulamanın bozuk görünmesini sağlarlar.
Bu yüzden Vue 3 i18n iş akışı, kullanılan kütüphaneden daha önemlidir. Kütüphane sizden isteneni yapar. Ölçek büyüdükçe ekipler genellikle “bitti”nin ne olduğu konusunda anlaşamaz.
Yaygın bir örnek: bir geliştirici 40 yeni string içeren yeni bir "Takımı davet et" akışı gönderir. İngilizce dosya güncellenir, ama Fransızca dosya güncellenmez. Staging'de her şey iyi görünür çünkü test eden kişi İngilizce kullanır. Prodüksiyonda Fransız kullanıcılar çevrilmiş ve çevrilmemiş UI karışımı görür ve destek ham anahtarların ekran görüntülerini alır.
Çözüm, çevrilmiş UI için “bitti”nin ne anlama geldiğini tanımlamaktır. Sadece "stringler eklendi" olamaz. Pratik bir “done” tanımı genellikle şunları içerir: anahtarlar adlandırma kurallarına uyuyor, locale'ler eksik-anahtar uyarıları olmadan derleniyor, çoğullar ve değişkenler gerçek veriyle doğru render oluyor, en az bir varsayılan olmayan locale kontrol edildi ve metin değişiklikleri izleniyor ki eski anahtarlar kalıntı olarak kalmasın.
500+ anahtarda, yerelleştirmeyi son dakika dosya düzenlemesi gibi değil bir yayın süreci gibi ele alarak kazanırsınız.
Birkaç yüz stringden sonra çeviri işi karışık olan taraf değildir. Tutarlılık sorun çıkarır. Küçük bir kural seti, birden çok kişi her hafta metne dokunsa bile Vue 3 i18n iş akışınızı öngörülebilir kılar.
Önce bir “kavram”ın ne olduğunu ve onun için tek bir doğruluk kaynağı tutmayı kararlaştırın. Aynı UI fikri beş yerde görünüyorsa (örneğin “Değişiklikleri kaydet”), beş anahtar yerine tek bir anahtar istersiniz; save, saveChanges, save_update ve saveBtn gibi varyantlar yerine. Çoğaltılmış anahtarlar zaman içinde anlam kaydırır ve kullanıcılar bu tutarsızlığı hisseder.
Sonra formatlamanın nerede olacağını kararlaştırın. Ekipler bunu kazara böler: bazı mesajlar noktalama ve büyük/küçük harf dahil olurken, diğerleri bunu kodun eklemesine güveniyor. Bir yaklaşım seçin ve ona uyun.
Pratik bir varsayılan:
Sonra sahipliği tanımlayın. Kim yeni anahtar ekleyebilir, kim baz dili kopyasını inceler ve kim diğer locale'leri onaylar karar verin. Bunu yapmazsanız stringler aceleyle eklenir ve hiç gözden geçirilmez.
Son olarak bir fallback stratejisi seçin ve dokümante edin. Bir anahtar eksikse kullanıcı ne görmeli: anahtar adı mı, varsayılan-dil metni mi yoksa güvenli genel bir mesaj mı? Prodüksiyonda birçok ekip, kullanıcıların engellenmemesi için varsayılan locale'e düşmeyi ve aynı zamanda bir log bırakmayı tercih eder; böylece bir şeylerin yanlış olduğunu görürsünüz.
AppMaster gibi bir jeneratörle (Vue3 web UI artı gerçek backend kodu) Vue 3 uygulamaları inşa ediyorsanız, bu kurallar yine geçerlidir. Çevirileri "sadece geliştirici metni" gibi değil ürün içeriği gibi ele alın, çoğu geç sürprizi önlersiniz.
Birkaç yüz stringin ötesinde, tutarlılık en büyük çarpandır. Bir anahtar stiline karar verin (çoğu ekip billing.invoice.title gibi dot path'leri kullanır) ve bunu kural yapın. Nokta, slash, snake_case ve rastgele büyük/küçük karışımı aramayı ve incelemeyi yavaşlatır.
Kopya değişikliklerinden sağ kalan kararlı anahtarları tercih edin. "Lütfen e-postanızı girin" gibi bir anahtar, pazarlama cümleyi değiştirir değiştirmez kırılır. auth.email.required veya auth.email.invalid gibi niyet-temelli isimleri tercih edin.
Anahtarları önce ürün alanına veya UI yüzeyine göre gruplayın, sonra amaca göre. Uygulamanızın zaten kullandığı kovalar gibi düşünün: auth, billing, settings, support, dashboard. Bu locale dosyalarını taramayı kolaylaştırır ve iki ekranın aynı fikre ihtiyacı olduğunda çoğaltmaları azaltır.
Her alan içinde, ortak UI parçaları için küçük bir desen seti tutun:
*.actions.save, *.actions.cancel*.fields.email.label, *.fields.password.label*.fields.email.hint*.errors.required, *.errors.invalidFormat*.notices.saved, *.notices.failedDinamik mesajlar neyin değiştiğini söylemeli, nasıl değiştiğini değil. Mesajı niyet ile adlandırın ve değişken parçalar için parametre kullanın. Örneğin, billing.invoice.dueInDays ve {days} billing.invoice.dueIn3Days’ten daha açıktır.
Örnek (Vue 3 i18n iş akışında güzel çalışır): orders.summary.itemsCount için {count} numara, ve orders.summary.total için {amount} para. Kodda bir anahtarı okuyan biri, final kopya değişse bile bunun nerede ve neden kullanıldığını anlamalıdır.
Her dili İngilizce gibi ele aldığınızda çoğul metinler sessizce bozulur. Hangi durumlarda ICU mesaj sözdizimini, hangi durumlarda basit yer tutucuyu kullanacağınızı erken kararlaştırın.
Sayıya göre değişmeyen etiketler ve kısa UI metinleri için basit değiştirmeler kullanın (örneğin, "Welcome, {name}"). Sayı bazlı her şey için ICU'ya geçin; çünkü tüm formları tek yerde tutar ve kuralları açık yapar.
{
"notifications.count": "{count, plural, =0 {No notifications} one {# notification} other {# notifications}}"
}
Sayısal mesajları çeviri için kolay olacak şekilde yazın. Tam bir cümleyi tercih edin ve sayı yer tutucusunu (#) isimle yakın tutun. "1 öğe" ve "2 öğe" için aynı anahtarı kodda yeniden kullanmak gibi yaratıcı kısayollardan kaçının. Çevirmenlerin tüm mesajı görmesi gerekir; nasıl birleştirileceğini tahmin etmemeliler.
En azından =0, one ve other için plan yapın ve 0 için ne beklediğinizi dokümante edin. Bazı ürünler "0 öğe" ister, bazıları "Öğe yok". Bir stil seçin ve ona bağlı kalın ki UI tutarlı olsun.
Ayrıca beklenenden daha fazla çoğul kategorisi olan diller için dikkatli olun. Birçok dil “bir vs birçok” şeklinde davranmaz. Daha sonra yeni bir locale eklerseniz, sadece one ve other içeren bir mesaj dilbilgisel olarak yanlış olabilir, hatta render olsa bile.
Göndermeden önce çoğulları UI'da gerçek sayılarla test edin, yalnızca JSON'a bakmayın. Çoğu sorunu yakalayan hızlı kontrol: 0, 1, 2, 5 ve 21.
Bir Vue3 web uygulaması inşa ediyorsanız (örneğin AppMaster içinde), bu testi metnin göründüğü gerçek ekranda yapın. Yerleşim problemleri, kesilmiş metin ve garip ifadeler orada ilk ortaya çıkar.
Birkaç yüz stringden sonra tek bir büyük en.json darboğaz olur. Aynı dosyaya birçok kişi dokunur, merge çatışmaları artar ve kopyanın nerede olduğu kaybolur. İyi bir yapı, ürün değişmeye devam ederken Vue 3 i18n iş akışınızı dengede tutar.
2 ila 5 locale için, özelliğe göre bölmek genellikle yeterlidir. Her locale içinde aynı dosya düzenini tutun, böylece anahtar eklemek öngörülebilir bir düzenleme olur.
locales/en/common.json, locales/en/auth.json, locales/en/billing.jsonlocales/es/common.json, locales/es/auth.json, locales/es/billing.jsonlocales/index.ts (mesajları yükler ve birleştirir)20+ locale için aynı fikri ölçeklendirin ama sapmayı zorlaştırın. İngilizceyi ana kaynak olarak kabul edin ve her locale'in aynı klasör ve dosya adlarını yansıtmasını zorunlu kılın. Yeni bir domain görünürse (örneğin notifications), tüm locale'lerde o domain olmalı, metin geçici bile olsa.
Domaine göre bölmek merge çatışmalarını azaltır; iki kişi farklı dosyalara string ekleyebilir ve birbirine basmaz. Domainler uygulamanızın yapısıyla eşleşmeli: common, navigation, errors, settings, reports ve daha büyük alanlar için feature klasörleri.
Her dosya içinde, aynı anahtar şeklini locale'ler arasında koruyun: aynı nesting, aynı anahtar adları, farklı metin. Dilde "yaratıcı" anahtarlardan kaçının, bir ifade çevirmesi zor olsa bile. İngilizcenin billing.invoice.status.paid ihtiyacı varsa, her locale'in o tam anahtarı olmalı.
Gerçekten her yerde tekrarlananları merkezileştirin: buton etiketleri, genel doğrulama hataları ve global navigasyon. Özellik-spesifik metni feature domainine yakın tutun, tekrar kullanılabilir gibi gelseler bile. "Kaydet" common'a ait. "Ödeme yöntemini kaydet" billing'e ait.
Uzun yardım metinleri, onboarding adımları ve e-posta şablonları hızla karışır. Birkaç kural yardımcı olur:
help veya onboarding) ve derin iç içe geçmeden kaçının.Bu kurulum değişiklikleri gözden geçirmeyi, çeviri akışını ve sürpriz boşlukları yayın öncesi önlemeyi kolaylaştırır.
Kararlı bir Vue 3 i18n iş akışı araçlardan çok her seferinde aynı küçük adımları tekrarlamaya dayanır. Yeni UI metni, bir anahtar, bir varsayılan mesaj ve net bir çeviri durumu olmadan prodüksiyona ulaşmamalıdır.
Önce anahtarınızı baz locale'e (genellikle en) ekleyin. Varsayılan metni gerçek kopya gibi yazın, yer tutucu gibi değil. Bu ürün ve QA için okunabilir bir şey verir ve "gizemli string" oluşmasını önler.
Bir bileşende anahtarı kullandığınızda, çeviri şeklinin tüm parametrelerini ve çoğul mantığını baştan ekleyin ki çevirmenler mesajın tam şeklini görsün.
// simple param
$t('billing.invoiceDue', { date: formattedDate })
// plural
$t('files.selected', count, { count })
Çeviriler hazır değilse anahtarları eksik bırakmayın. Diğer locale'lere yer tutucu çeviriler ekleyin veya tutarlı bir şekilde beklemede (TODO: ile başlayan) işaretleyin. Önemli olan uygulamanın öngörülebilir şekilde render olması ve gözden geçirenlerin eksik metni kolayca fark etmesidir.
Merge etmeden önce hızlı otomatik kontroller çalıştırın. Bunları sıkıcı ve katı tutun: locale'ler arasında eksik anahtar uyarıları, kullanılmayan anahtarlar, yer tutucu uyuşmazlıkları ({count}, {date} eksikliği veya yanlış süslü parantez), desteklenen diller için geçersiz çoğul formları ve kazara üzerine yazmalar.
Son olarak en az bir varsayılan olmayan locale'de kısa bir UI kontrolü yapın. Uzun stringlere sahip bir dili seçin (çoğunlukla Almanca veya Fransızca) ki taşma, kesilmiş butonlar ve garip satır kırılmaları çıksın. Eğer Vue 3 UI'nız AppMaster gibi bir araçla üretiliyorsa veya ürünün diğer parçalarıyla birlikte yönetiliyorsa, bu adım önemini korur çünkü yerleşimler özelliklerle değişir.
Bu adımları, metin ekleyen her özellik için "done" tanımınız olarak ele alın.
Yerelleştirmeyi zorlaştırmanın en hızlı yolu i18n anahtarlarını "sadece string" gibi ele almaktır. Birkaç yüz anahtardan sonra küçük alışkanlıklar prodüksiyon hatalarına dönüşür.
Yazım hataları ve büyük/küçük harf farkları eksik metnin klasik nedenleridir: bir yerde checkout.title, diğer yerde Checkout.title. Kod incelemede sorun görünmeyebilir, sonra fallback dili sessizce gönderilir.
Bir diğer yaygın sorun aynı anahtarın farklı anlamlar için tekrar kullanılmasıdır. “Open” destek ekranında “Bileti aç” anlamında, mağaza sayfasında “Şimdi aç” anlamında olabilir. Tek bir anahtar tekrar kullanılırsa, bu ekranlardan biri diğer dillerde yanlış olur ve çevirmen tahmin yapmak zorunda kalır.
Basit bir kural yardımcı olur: bir anahtar bir anlama eşittir. Anlam değişirse, İngilizce aynı bile olsa yeni bir anahtar oluşturun.
Ekipler genellikle noktalama, boşluk veya HTML parçalarını çeviriye gömer. Bu, bir dil farklı noktalama gerektirdiğinde veya UI markup'u farklı şekilde escape/işlediğinde bozulur. Markup kararlarını şablonlarda tutun, mesajları sadece metne odaklı tutun.
Mobilde problemler saklıdır. İngilizcede sığan bir etiket Almanca'da üç satıra sarılabilir veya Tay dilinde taşabilir. Sadece tek bir ekran boyutunu test ederseniz, bunları kaçırırsınız.
Tekrarlayan suçlulara dikkat edin: değişkenleri yerleştirirken İngilizce kelime sırasını varsaymak, parçaları birleştirerek mesaj oluşturmak yerine tek bir mesaj kullanmamak, uzun değerleri (ürün isimleri, adresler, hata detayları) test etmemek, eksik anahtar için sessiz fallback etkin halde gönderim yapmak ve İngilizce değeri düzenlerken anahtarları kopyala-yapıştır yapıp sadece İngilizceyi değiştirmek.
Eğer 500+ anahtarda sakin kalan bir Vue 3 i18n iş akışı istiyorsanız, anahtarları API'nızın bir parçası gibi ele alın: kararlı, spesifik ve diğer her şey gibi test edilmiş.
Eksik çeviriler uygulamanın hâlâ “çalışıyor” görünmesi nedeniyle kolayca kaçırılır. Sadece anahtara, yanlış locale'e veya boş string'e düşer. Çeviri kapsamasını testler gibi ele alın: prodüksiyona gitmeden önce hızlı geri bildirim istiyorsunuz.
Build'i kıran kontrollerle başlayın; kimsenin okumadığı uyarılar yazdıran kontrollerle değil.
$t('...') ve t('...') kullanımına göre tarayın, sonra kullanılan her anahtarın baz locale'de var olduğunu doğrulayın.İstisna listesini kısa ve takımın sahip olduğu tutun; “ne geçerse CI geçer” gibi bir yaklaşım değil.
CI olsa bile gerçek kullanıcı yolları unuttuğunuz stringleri tetikler; bu yüzden staging'de bir ağ istiyorsunuz.
Staging'de eksik-çeviri loglamayı etkinleştirin ve hızlı düzeltme için yeterli bağlam içeren bilgiyi ekleyin: locale, route, bileşen adı (varsa) ve eksik anahtar. Gürültülü yapın. Kolay görmezden gelinirse, görmezden gelinir.
Bir pseudo-locale ekleyin ve hızlı bir UI turu için kullanın. Basit bir yaklaşım: her stringi dönüştürmek (uzunlaştırmak ve işaret koymak) ki yerleşim problemleri hemen göze çarpsın; örneğin: [!!! 𝗧𝗲𝘅𝘁 𝗲𝘅𝗽𝗮𝗻𝗱𝗲𝗱 !!!]. Bu, kesilen butonları, kırık tablo başlıklarını ve eksik boşlukları yayın öncesi yakalar.
Son olarak, yayın öncesi en yüksek değerli yolları 2-3 locale'de kısa bir kontrolden geçirin: giriş, ödeme/checkout, ana ayarlar ve yayınladığınız yeni özellik. Burada "çevrildi ama yer tutucu yanlış" hatalarını yakalarsınız.
Yeni bir dil eklemek, onu "sadece metin işi" olarak ele aldığınızda karmaşıklaşır; bunun yerine küçük bir ürün yayını olarak ele alın. Vue 3 i18n iş akışınızı stabil tutmanın en kolay yolu, bir locale eksik olsa bile uygulamanın derlenmesini sağlamak ama boşlukların kullanıcılara görünmeden önce açıkça fark edilmesini sağlamaktır.
Yeni bir locale eklerken önce yapıyı oluşturun, çeviri yapmayın.
en) tam anahtar seti ile oluşturun.Çeviriler genellikle geç gelir; bu yüzden "kısmi"nin ürün için ne anlama geldiğine önceden karar verin. Bir özellik müşteri yüzündeyse, özellik ve stringler birlikte gönderilecek şekilde feature flag düşünün. Eksik çevirilerle gönderilmek zorundaysa, boş etiketler yerine açık bir fallback (örneğin İngilizce) tercih edin, ama bunu staging'de yüksek seste yapın.
Metin güncellemeleri ekiplerin anahtarları bozan noktasıdır. Wording değiştirirseniz anahtarı stabil tutun. Anahtarlar tam cümleyi değil niyeti tanımlamalı. Anahtar yeniden adlandırmasını anlam değişikliği olduğunda yapın ve bunu kontrollü bir taşıma ile gerçekleştirin.
"Zombi stringlerden" kaçınmak için anahtarları kasıtlı olarak kullanımdan kaldırın: anahtarları kullanım dışı ilan edin, bir tarih ve yerine geçen anahtarı not edin, bir yayın döngüsü boyunca tutun ve sonra referans kalmadığını doğruladıktan sonra kaldırın.
Çeviri notlarını anahtarın yakınında tutun. JSON formatınız yorum tutamıyorsa, küçük bir yardımcı doküman veya bitişik metadata dosyası kullanın (örneğin, "checkout başarı ekranında kullanılıyor"). Bu, AppMaster gibi bir araçla Vue 3 web uygulaması üretildiğinde ve birçok kişi kopya ve UI'ya dokunduğunda özellikle faydalıdır.
Bir sprintte ekip aynı anda üç şeyi gönderir: yeni bir Ayarlar sayfası, bir Faturalama ekranı ve üç e-posta şablonu (fiş, ödeme başarısız, deneme bitişi). Bu yaklaşık 60 yeni string demektir ve i18n sıkça burada karışır.
Ekip, anahtarları özelliğe göre, sonra yüzeye göre gruplamayı kabul eder. Her özellik için yeni bir dosya oluşturulur ve anahtarlar her yerde aynı paterni takip eder: feature.area.element.
// settings
"settings.profile.title": "Profile",
"settings.security.mfa.enable": "Enable two-factor authentication",
// billing
"billing.plan.current": "Current plan",
"billing.invoice.count": "{count} invoice | {count} invoices",
// email
"email.receipt.subject": "Your receipt",
"email.payment_failed.cta": "Update payment method"
Çeviri çalışması başlamadan önce çoğul stringler gerçek değerlerle test edilir, tahminlerle değil. billing.invoice.count için QA 0, 1, 2 ve 5'i seeded veriyle (veya basit bir dev toggle ile) kontrol eder. Bu, "0 invoice" gibi garip vakaları erken yakalar.
QA sonra eksik anahtarları ortaya çıkarma eğiliminde olan odaklanmış bir akış çalıştırır: Ayarlar ve Faturalamayı açın ve her sekmeye bir kere tıklayın, e-posta şablonlarını staging'de test hesaplarıyla tetikleyin, uygulamayı varsayılan olmayan bir locale ile çalıştırın ve loglarda eksik-çeviri uyarısı varsa build'i kırın.
Bu sprintte QA iki eksik anahtar bulur: Faturalama ekranında bir etiket ve bir e-posta konusu. Ekip bunları yayından önce düzeltir.
Yayımlamayı engelleme veya fallback'e izin verme kararında basit bir kural kullanırlar: kullanıcıya açık ekranlar ve işlem e-postaları yayını engeller; düşük riskli admin-only metinler varsayılan dile geçici düşebilir ama sadece bir ticket ve net bir son tarihle.
Vue 3 i18n iş akışı, çevirileri kod gibi ele aldığınızda stabil kalır: her seferinde aynı şekilde ekleyin, test edin ve puanlayın.
Birkaç basit sayı seçin ve düzenli gözden geçirin: test çalıştırmanızdaki eksik-anahtar oranı, varsayılan olmayan locale'lerde çevrilmemiş string sayısı ve kullanılmayan anahtar sayısı (artık hiçbir yerde görünmeyen stringler). Bunları mümkünse sürüm başına takip edin ki tekil hatalar yerine trendleri görün.
Bir string ekleme, çeviri güncelleme ve sonucu doğrulama için tam adımları yazın. Kısa tutun ve anahtar adlarına ve çoğul kullanımına örnekler ekleyin. Yeni katkıda bulunanlar soru sormadan izleyebilmeli.
Eğer dahili araçlar inşa ediyorsanız, AppMaster (appmaster.io) Vue3 web uygulaması ve companion mobil uygulamalar arasında UI metni ve çeviri anahtarlarını tutarlı tutmak için pratik bir yol olabilir; çünkü her şey tek bir yerde yönetilir.
Her sprintte küçük bir i18n sağlık görevi planlayın: kullanılmayan anahtarları silin, tutarsız yer tutucuları düzeltin ve son kaçırmaları gözden geçirin. Küçük temizlikler prodüksiyonda acil çeviri aramalarından daha iyidir.
21 Oca 2026
8 dk
20 Oca 20268 dk
20 Oca 20268 dkÜcretsiz planla AppMaster ile denemeler yapın.
Hazır olduğunuzda uygun aboneliği seçebilirsiniz.
