İlerleme Çubuğu API Değildir: CLI ile Olay Akışını Ayırmak

Co-op Translator v0.20.0, bir CLI aracının en sık düşülen tuzaklarından birini çözüyor: ilerleme çubuğu gibi insan odaklı çıktıların, zamanla bir entegrasyon sözleşmesine dönüşmesi. Ekip, aynı durumu iki farklı yüzeye ayırarak çözmüş: Rich kütüphanesiyle üretilen okunabilir CLI arayüzü ve yapılandırılmış olay akışı (stage_started, stage_progress, file_completed, run_completed gibi). Böylece CLI'nin görsel metni değiştikçe dış sistemlerin bozulması riski ortadan kalkıyor.

Bu ayrımın kalbinde stage_label ile stage_key arasındaki fark var; label görüntü metni olarak serbestçe değişebilirken, key entegrasyonların bağlanması gereken sabit değer olarak kalıyor. Aynı olay sözleşmesi CLI'de NDJSON dosyası, Python API'de progress_callback, MCP'de ise araç sonucu payload'ı üzerinden aynı şekilde sunuluyor. Bu, tek bir iç durumun birden fazla arayüze tutarlı şekilde yayılmasını sağlıyor.

Sonuç, Localizeflow gibi ürün entegrasyonları için pratik bir fark yaratıyor: konsol satırlarını ayrıştırıp anlam çıkarmaya çalışmak yerine, doğrudan veritabanına yazılabilecek durable olaylar tüketiliyor. Loglar hâlâ hata ayıklama için değerli, ama artık ürün durumunun tek kaynağı değil. Bu yaklaşım, CLI/UI'nin okunabilirlik açısından gelişmeye devam edebilmesini sağlarken API ve MCP entegrasyonlarının kararlılığını korumak isteyen mühendisler için iyi bir tasarım örneği sunuyor.