← Öğren

Sorun giderme

Buradaki her kayıt, gerçekten birinin karşılaştığı bir hata durumudur. Her biri belirtiyi, neden oluştuğunu ve çözümünü listeler. Çoğu şu üç şeyden birine dayanır: ifade projede yok, SDK hiç başlatılmadı ya da bir yer tutucu yanlış bağlam için yazıldı.

Hiçbir şey çevrilmiyor — her ifade kaynak dilde kalıyor

Her şey kaynak metni gösteriyorsa SDK büyük olasılıkla başlatılamamıştır. Tasarım gereği sessizce başarısız olur (arayüzünüz asla bozulmamalıdır), bu yüzden tek belirgin işaret tarayıcı konsoludur — önce oraya bakın. Olası nedenler, yaygınlık sırasına göre:

1. CORS. SDK'nın ilk isteği authorize-project isteğidir; API'niz uygulamanın origin'ini izin listesine eklemezse tarayıcı isteği engeller ve başlatma işlemi tam orada sona erer. Bir origin'in tam olarak şema + ana makine + port olduğunu unutmayın — localhost:5173 ve localhost:5174 farklı origin'lerdir ve geliştirme sunucuları her zamanki port doluysa başka bir porta kayar. Gerçekten geliştirme yaptığınız her portu izin listesine ekleyin.
2. Hatalı kimlik bilgileri. Eksik veya yanlış yazılmış bir proje kimliği / API anahtarı aynı yetkilendirme çağrısının başarısız olmasına yol açar. Konsol, başarısız olan isteği ve URL'yi gösterir.
3. Temel dile bakıyorsunuz. Temel dilde "çeviri" zaten kaynak metnin kendisidir; görünürde hiçbir şey değişmez. Test etmek için bir hedef dile geçin.

# The SDK's first call is an authorize-project request.
# If the browser blocks it, NOTHING translates. Check the console for:
Access to fetch at 'https://your-api/api/authorize-project/...'
from origin 'http://localhost:5173' has been blocked by CORS policy

# Fix: allowlist the app's EXACT origin (scheme + host + port) on the API.
CORS_ALLOWED_ORIGINS=http://localhost:5173,https://app.example.com

Bir ifade çevrilmiyor (ama diğerleri çevriliyor)

Kodunuzdaki ifade arama anahtarıdır — ifade anahtardır. Tek bir ifade kaynak metin olarak görünürken komşuları çevriliyorsa, o anahtar projenin kataloğunda yoktur:

• Hiç kaydedilmedi. Kayıt işlemi belirteç keşfi üzerinden gerçekleşir ve bunu yalnızca bir yazma anahtarı yapabilir. İfade, uygulama salt okunur bir anahtarla çalışırken oluştuysa hiçbir yere gönderilmemiştir — ekranı geliştirme ortamında bir yazma anahtarıyla bir kez çalıştırın veya ifadeyi panodan ekleyin.
• Metin değişti. Herhangi bir düzenleme — bir kelime, noktalama işareti, hatta boşluk — onu henüz çevirisi olmayan yeni bir ifade yapar. Eski çeviriler eski anahtarın altında durmaya devam eder. Bu durum özellikle içerik bloklarında can sıkar: bir <Translate> bloğu işaretlemesinden token'lara ayrılır; bu yüzden bloğun metnini veya yapısını düzenlemek aranan şeyi değiştirir ve yeni biçim kaydedilip çevrilene kadar blok sessizce kaynak metne geri döner.
• Makine çevirisi henüz yetişemedi. Yeni kaydedilen bir ifadenin çevirileri kısa bir süre gecikebilir; projenin hedef listesinde olmayan bir yerel ayar için ise çeviri hiç oluşturulmaz. İfadeyi kontrol panelinde kontrol edin: kayıtlı mı? bu yerel ayara çevrilmiş mi?

Eksik ifadeler neden hata vermez?

Bu bilinçli bir tasarım. Üretimde bir çeviri sistemi, bozuk bir sayfa yerine okunabilir kaynak metne düşmelidir; bu yüzden kayıtlı olmayan bir ifade kaynak metniyle görüntülenir ve SDK sessiz kalır. Bunun diğer yüzü: salt okunur bir anahtarla eksik bir ifade sessizce geçer. Hiçbir şey günlüğe yazılmaz, hiçbir şey kaydedilmez ve durumu ilk fark etmeniz, bir kullanıcının İngilizce metin görmesiyle olur. Bunu önleyen yöntem anahtar ayrımıdır: arayüzünüzün oluşturduğu her ifade keşfedilsin diye yazma anahtarıyla geliştirin, ardından salt okunur olarak yayınlayın.

# Development — write key: new phrases are discovered,
# registered, and machine-translated as you build.
VITE_LANGSYS_API_KEY=write-key

# Production — read-only key: fetches the finished catalog only.
# Unregistered phrases silently render their source text.
VITE_LANGSYS_API_KEY=read-only-key

Yer tutucum olduğu gibi görünüyor — "Hi %name%" veya "Hi {name}"

• t() çağrılarında yer tutucular tek süslü parantezlidir: {name}. Enterpolasyon yalnızca parametreleri ilettiğinizde çalışır: t('Hello, {name}!', 'Greetings', { name }).
• React, Vue veya Svelte altında <Translate>/<Phrase> işaretlemesinde yer tutucuları %name% biçiminde yazın. Framework derleyicisi, SDK daha görmeden çıplak bir {name} ifadesini bir ifade (expression) olarak işler; %name% ise derlemeden sağ çıkar ve SDK onu yakalama sırasında tekrar {name} biçimine normalleştirir. Çakışabilecek bir şablon sözdizimi bulunmayan düz HTML'de ise sade {name} kullanmak sorun değildir.
• Parametreler eksik mi? Hiç params sağlanmazsa şablon olduğu gibi işlenir; gördüğünüz de tam olarak %name% ifadesidir.

Çalışıyor, ama yerel ayarlar arasında ileri geri geçiş yaptıktan sonra bozuluyor

SDK'yı güncelleyin. Bu alanda gerçekten düzeltilmiş hatalar: başlangıç/SSR diline dönmek önceki kataloğun etkin kalmasına neden oluyordu (langsys-js-typescript 0.2.2'de düzeltildi) ve içerik bloğu Translate/Phrase kullanan bileşenler sunucuda tohumlanmış bir katalogda sonsuza kadar takılı kalabiliyordu (0.2.3'te düzeltildi). Eski dile ait metinler veya hiç çözümlenmeyen bloklar görüyorsanız, kendi kodunuzda hata ayıklamadan önce yüklü sürümünüzü temel SDK'nın değişiklik günlüğüyle karşılaştırın.

Sunucu tarafı: sayfa zarif biçimde düşmek yerine 500 hatası veriyor

PHP SDK'sının istemcisi kimlik bilgileri olmadan oluşturulduğunda hata fırlatır; bu yüzden boş bir LANGSYS_API_KEY değerine sahip bir Laravel (veya düz PHP) uygulaması, herhangi bir çeviri çalışmadan önce, container çözümlemesi sırasında hata verir. Kimlik bilgilerini ayarlayın (ya da bunlar olmadan açılması gereken bir uygulamada, demo uygulamalarının yaptığı gibi yerine geçen bir istemci bağlayın). Kimlik bilgileri tanımlandıktan sonra çalışma zamanındaki API hataları yumuşak biçimde ele alınır: ulaşılamayan veya isteği reddeden bir API kaynak metni gösterir ve istisnayı bildirir; sayfayı asla çökertmez.

Sunucu tarafı: ilk istek takılı kalıyor, sonra her şey hızlı

PHP SDK'sının HTTP zaman aşımı 30 saniyedir ve boşta bekleyen bir API örneği uyanırken ilk çağrıda bu süreye yaklaşabilir. Bu istek ya yavaş tamamlanır (ve katalog önbelleğini ısıtır; sonrasındaki her şey önbellekten sunulur) ya da zaman aşımına uğrar ve kaynak metin görüntülenir. Sessiz bir dönemin ardından ilk sayfa yüklemeniz yavaşsa nedeni budur; bu, API'nin ısınmasıdır, entegrasyonunuzdan kaynaklanmaz.

Sunucu tarafı: Yazma anahtarıyla oluşturdum ama ifade kontrol panelinde görünmüyor

Keşfedilen ifadeler istek sırasında kuyruğa alınır ve yanıt gönderildikten sonra iletilir — Laravel'in terminable middleware yapısı. Panoyu sayfa yüklenirken değil, yüklendikten kısa bir süre sonra yenileyin. Uzun ömürlü worker çalışma ortamlarında (Octane, FrankenPHP, RoadRunner) SDK'nın sunduğu entegrasyonu kullandığınızdan emin olun; düz PHP kapatma kancası (shutdown hook) worker istekleri arasında hiç tetiklenmez.

Sunucu tarafı oluşturma: bir isteğin çevirileri başka bir isteğe karışıyor

JS temel SDK'sı aynı anda yalnızca tek bir yerel ayarın kataloğunu tutar; modül düzeyinde bir tekil nesnedir. Eşzamanlı isteklere farklı yerel ayarlar sunan bir Node sunucusunda yarış durumu oluşur. Kataloğu istek başına alıp istemciyi bununla başlatın; bu, Next.js, Nuxt ve SvelteKit kılavuzlarındaki yaklaşımdır. Alternatif olarak süreç başına tek bir yerel ayar çalıştırın.