Kurallar

Bu sayfa, kod adlandırma, i18n çeviri sözlüğü ve Çince üslup rehberi için tek gerçek kaynaktır. Eskiden packages/views/locales/glossary.md'de veya dağınık yorumlarda yaşayan her şey artık burada yaşıyor.

Multica kodu yazıyorsanız, bir çeviriyi değiştiriyorsanız veya Çince ürün metni yazıyorsanız, referans alacağınız sayfa budur.

1. Kod adlandırma

Rotalar

Çalışma alanı öncesi rotalar (kullanıcı bir çalışma alanına girmeden önce var olan rotalar) ya tek bir kelime ya da /{noun}/{verb} kalıbını kullanMALIDIR.

• ✅ /login, /inbox, /workspaces/new
• ❌ /new-workspace, /create-team, /accept-invite

Kökte tire ile ayrılmış kelime grupları, kullanıcının seçtiği çalışma alanı kısa adlarıyla çakışır ve sonsuz rezerve-kısa-ad denetimlerini zorunlu kılar. İsmi (workspaces) rezerve etmek, tüm /workspaces/* alt ağacını otomatik olarak korur.

Çalışma alanı kapsamlı rotalar

Her zaman /{slug}/{section} altında yaşar — /{slug}/issues, /{slug}/agents, /{slug}/settings. Çalışma alanı yönlendirme mantığını asla çoğaltmayın; paylaşımlı koddan useNavigation().push() kullanın, asla framework'e özel bağlantı API'leri kullanmayın.

Paketler ve modüller

Monorepo katı paket sınırlarını uygular:

Mantık her iki uygulamada da görünüyorsa, paylaşımlı bir pakete çıkarılMALIDIR. "Küçük" çoğaltma için istisna yoktur. Mobil; ayrı bir arayüze, veri katmanına ve sürüm sürecine sahiptir; yalnızca tipleri ve saf fonksiyonları paylaşır.

Dosyalar ve bileşenler

• Dosyalar: kebab-case.tsx / kebab-case.ts (örn. agent-row-actions.tsx)
• Bileşenler: PascalCase (örn. AgentRowActions)
• Hook'lar: useCamelCase (örn. useWorkspaceId)
• Testler: <file>.test.ts(x) olarak yan yana
• Store'lar (Zustand): <feature>-store.ts, use<Feature>Store olarak dışa aktarılır

Veritabanı (Go + sqlc)

• Tablolar: snake_case tekil (user, workspace, agent_runtime)
• Sütunlar: snake_case (workspace_id, created_at, last_seen_at)
• Yabancı anahtarlar: <table>_id
• Boolean'lar: is_<state> veya <state>_at (durum değişiklikleri için zaman damgası biçimi tercih edilir)
• Migration dosyaları: NNN_descriptive_name.up.sql + .down.sql — her zaman iki yönü de sağlayın
• Veritabanında yabancı anahtar oluşturmayın, cascade silme veya güncelleme kullanmayın; ilişkileri ve temizliği uygulama katmanında sağlayın.
• Her indeks CREATE INDEX CONCURRENTLY veya CREATE UNIQUE INDEX CONCURRENTLY kullanmalı ve her eşzamanlı indeks kendi tek ifadeli migration dosyasında olmalıdır.

Go

• Standart gofmt + go vet. İstisna yok.
• İşleyici dosyaları alanı yansıtır: agent.go, auth.go, runtime.go
• Testler: <file>_test.go yan yana
• İşleyicilerde UUID ayrıştırma için, kök AGENTS.md'deki kuralı izleyin — sınır girdisi için parseUUIDOrBadRequest, güvenilen round-trip'ler için parseUUID (panikleyen), hatayı kontrol etmeden asla doğrudan util.ParseUUID kullanmayın.

TypeScript

• Tel üzerindeki API yanıtları snake_case'dir; api istemcisi sınırda camelCase'e dönüştürür. TS kodunun içinde, her zaman camelCase.
• Tipler: PascalCase (Issue, AgentRuntime); asla IPrefix, asla _t soneki.
• Enum'lar: dize literal birleşimlerini tercih edin; enum'u çalışma zamanında yinelenebilir durumlar için saklayın.
• TanStack Query anahtarları: <feature>/queries.ts'de fabrika fonksiyonları, örn. issueKeys.detail(id).

API sınırları

• Ağ yanıtlarını parseWithFallback ve packages/core/api/schema.ts'deki zod şemalarıyla ayrıştırın; onları doğrudan as T ile dönüştürmeyin.
• Bir uç nokta eklerken veya değiştirirken şemasını güncelleyin ve eksik ya da bozuk alanları testlerde kapsayın.
• Aşağı akıştaki arayüz, isteğe bağlı alanlar için varsayılanlar sağlamalı ve bir sunucu enum'u üzerindeki her switch bir default dalı içermelidir.
• Kurulu bir Desktop istemcisi daha yeni bir backend'e bağlanabilir; frontend ve backend sürümlerinin her zaman eşleştiğini asla varsaymayın.

Runtime görünen adları

AgentRuntime.name, daemon'un ham teknik adıdır (örn. Codex (host)); kullanıcının takma adı custom_name'de yaşar. Kullanıcıya görünen metin runtime.name'i asla doğrudan render etmemelidir — takma adlar ve sağlayıcı tutarlı kalsın diye paylaşımlı yardımcıları kullanın (MUL-5248, #5260):

• Bağımsız runtime etiketi (listeler, çipler, onay iletişim kutuları, belge başlıkları): runtimeDisplayLabel(runtime) → takma ad + sağlayıcı, daemon adına geri düşer.
• Yanında zaten bir sağlayıcı simgesi/metni varsa: runtimeDisplayName(runtime) → yalnızca takma ad, sağlayıcı tekrarlanmaz.
• Bir makine grubunun içinde: makine başlığı machine.title, alt satırlar runtimeRowLabel(runtime, machine.title) kullanır.
• Runtime seçicileri buildRuntimeMachines ile makineye göre gruplar; ham adlardan düz bir liste oluşturmayın.

Ham runtime.name yalnızca dahili kimlik için izinlidir — ana makine adı ayrıştırma, gruplama, arama havuzları ve protokol yükleri — JSX metni, i18n parametreleri, <Select> etiketleri veya pencere başlıkları için asla.

İş anahtarları

Her işin MUL-123 gibi insan tarafından okunabilir bir anahtarı vardır: çalışma alanı issue_prefixi (büyük harf ve rakam, tipik olarak 3 karakter, en fazla 10) + sıra numarası. Çalışma alanı yöneticileri Ayarlar → Genel'de ön eki değiştirebilir; değiştirmek mevcut her işi yeniden numaralandırır, bu yüzden eski ön eki gömen dış referanslar (PR başlıkları, dal adları, dokümanlardaki ve sohbetteki bağlantılar) çözümlenmeyi durdurur.

Koddaki yorumlar

Yalnızca İngilizce. Repo bunu hem Go hem TypeScript için zorunlu kılar. Kodda bir Çince yorum bulursanız, bu bir hatadır — değiştirin.

Commit mesajları

Geleneksel biçim: feat(scope), fix(scope), refactor(scope), docs, test(scope), chore(scope). Niyete göre gruplandırılmış atomik commit'ler.

2. i18n çeviri sözlüğü

Bu, her çeviri PR'ı için zorunlu sözlüktür. Eskiden packages/views/locales/glossary.md'de yaşıyordu; o dosya kaldırıldı ve bu sayfa onun yerini aldı.

Temel ayrım: günlük kelime ve Multica'ya özgü terim

Multica'nın ürün isimleri iki kategoriye ayrılır:

• Günlük kelime — kullanıcının onun için sesli söyleyeceği kelime. Bir veritabanı varlığı olsun ya da olmasın tamamen çevrilir: issue → 任务, workspace → 工作区, project → 项目.
• Multica'ya özgü terim — hiçbir yerel kelimenin karşılamadığı bir kavram (skill) veya kullanıcının yazması ya da eşleştirmesi gerekebilecek şema düzeyinde bir tanımlayıcı (todo, in_progress, task_id). Bir tip adı gibi okunması için küçük harf İngilizce olarak render edilir.

apps/docs/content/docs/*.zh.mdx altındaki Çince sayfalar, bu sayfadaki diğer her şey için fiili üslup standardıdır. *.zh.mdx, *.ja.mdx ve *.ko.mdx metinleri artık aşağıdaki tabloyu da izliyor.

issue, ürünün görevidir — çevirin

issue, bir kullanıcının açtığı ve bir agent'ın üzerinde çalıştığı şeyin İngilizce ürün adıdır. Diğer her locale'de bu, "görev" için kullanılan günlük kelimedir:

Her iki kavram da kullanıcıya görünürdür ve aynı şey değildir — bir issue birçok run taşıyabilir. Hiçbir locale'de ikisini aynı kelimeyle yazmayın. Task, artık bir agent çalıştırması için kullanıcıya görünen bir ürün ismi değildir; yalnızca yerleşik dahili tanımlayıcı olarak kalır.

Değişmeyenler:

• API / DB alanları her yerde issue / task / skill olarak kalır: issue_status, task_id, skill_uuid. Geliştirici metni ürün nesnesini Run olarak adlandırır ve tanımlayıcı önemli olduğunda "Run (API'de task_id)" şeklinde açıklığa kavuşturabilir.
• Kod referansları ve gerçek komutlar İngilizce kalır: multica issue ..., /issue Slack ve Lark eğik çizgi komutu.
• skill Çince metinde küçük harf İngilizce kalır — yerleşmiş bir Çince terimi olmayan Multica'ya özgü bir kavram; başlıklar Skills olarak büyük harfle yazılabilir.
• "Problem" anlamındaki issue (runtime sağlığı) varlığın kendisi değil, düz bir isimdir: bir makine kartında {{count}} issues, {{count}} 个异常 / 問題 {{count}} 件 / 문제 {{count}}개 olur, asla varlık kelimesi olmaz.

Neden issue çevrilirken skill çevrilmiyor: kullanıcılar tüm gün issue açar ve okur, "issue"nun ise Çince, Japonca veya Korece'de geliştirici jargonu dışında bir anlamı yoktur. Günlük görev kelimesi, insanların bunun için zaten söylediği kelimedir. skill ise hiçbir yerel kelimenin anlamı taşımadığı Multica'ya özgü bir kavramdır.

Diğer ürün isimleri de aynı "yerleşik bir yerel kelimesi olanı çevir" testini izler:

• project → "项目": yerleşmiş ana akım Çince kelime. Feishu / Tower / Teambition / PingCode / GitHub Projects — her Çince ürün onu çevirir. Hiçbir ürün Çince bağlamda projecti korumaz.
• autopilot → "自动化": Çince'de, "autopilot" Tesla'nın "自动驾驶"siyle ilişkilendirilir ve özelliğin yaptığıyla eşleşmez (bir zamanlamaya göre agent çalıştırmaları başlatmak). Notion ve Feishu ikisi de "自动化" kullanır; bu endüstri konsensüsüdür.

Çevirme — markalar ve kısaltmalar

Tamamen çevir — kavramlar

Tamamen çevir — genel arayüz kelimeleri

Roller ve durum enum'ları (küçük harf İngilizce, çevrilmez)

Bunlar şema düzeyinde tanımlayıcılardır; Çince bağlamda bile küçük harf İngilizce olarak render edilir.

• Roller: owner / admin / member
• İş durumu: backlog / todo / in_progress / in_review / done / blocked / cancelled
• İş durumu kategorisi: unstarted / started / done / closed

Arayüzde, İngilizce olarak gösterin (isteğe bağlı code-style sarmalı):

• "你需要 owner 权限"
• "已切换到 in_progress"

Kelime birleştirme kuralları

Bir İngilizce kelime (varlık / marka / kısaltma) ile çevreleyen Çince arasına her zaman tek bir boşluk koyun:

• "Create new issue" → "新建任务"（任务 Çince olduğu için boşluk yok)
• "Assign to agent" → "分配给智能体"
• "Configure runtime" → "配置运行时"
• "Stop daemon" → "停止守护进程"

Çoğullar ve sayımlar

i18next _one / _other kullanır; Çince'de gramer sayısı yoktur, yalnızca _otherı doldurun.

// en/issues.json
{
  "issue_count_one": "{{count}} issue",
  "issue_count_other": "{{count}} issues"
}

// zh-Hans/issues.json
{
  "issue_count_other": "{{count}} 个任务"
}

Yaygın sayım biçimleri:

• {{count}} issues → {{count}} 个任务
• {{count}} agents → {{count}} 个智能体
• {{count}} workspaces → {{count}} 个工作区
• {{count}} comments → {{count}} 条评论
• {{count}} members → {{count}} 位成员
• {{count}} skills → {{count}} 个 skill

Enterpolasyon

{{var}} kullanın. Çince çeviriler doğal cümle akışı için yeniden sıralanabilir.

// en
{ "welcome_message": "Welcome back, {{name}}!" }

// zh-Hans
{ "welcome_message": "欢迎回来，{{name}}！" }

Çeviri anahtarı adlandırma

Üç düzeyli iç içe geçme: feature.component.action.

{
  "feature_or_component": {
    "subcomponent_or_section": {
      "action_or_label": "..."
    }
  }
}

Örnekler:

• issues.toolbar.batch_update_success
• issues.detail.comment_form.placeholder
• inbox.empty.title
• settings.preferences.language.title

Yalnızca web / yalnızca masaüstü metni

• Paylaşımlı metin: ad alanı JSON'ının üst düzeyi
• Yalnızca web: web bölümü
• Yalnızca masaüstü: desktop bölümü

Kanonik örnek için auth.json'a bakın (web bölümü prefer_desktop / desktop_handoff.* içerir).

3. Çince ses ve üslup

Noktalama

• Çince'de tam genişlikte noktalama: ，。：；！？
• Tırnaklar: İngilizce kaynakla eşleşmek için düz çift tırnak "...". 「」 veya kıvrık tırnak kullanmayın.
• Üç nokta: tek karakter … değil üç nokta .... İngilizce kaynakla eşleştirin.
• Karışık Çince-İngilizce: İngilizce kelimenin her iki tarafında tek bir boşluk (Kelime birleştirme kurallarına bakın).

Üslup ilkeleri

• Kısa ve doğrudan. Çeviri kokusundan kaçının: "对于 X 来说"、"作为 X"、"我们的".
• Hata mesajları: nazik ama net. "无法保存修改", "保存修改失败了！"den daha iyidir.
• Düğmeler: önce fiil, 2-4 karakter. "取消"、"保存修改"、"立即同步".
• Araç ipuçları: tam kısa cümle. "复制链接到剪贴板".
• Yer tutucular: örnek tarzı. "输入任务标题...".

Arayüz açıklamaları

Açıklamalar isteğe bağlıdır ve varsayılan olarak atlanır. Bir tane eklemeden önce sorun: Bu cümle olmadan kullanıcı neyi yanlış anlar veya yanlış yapar? Başlık, etiket, kontrol, değer veya düğme bunu zaten yanıtlıyorsa cümleyi atlayın.

• Bir olguyu bir kez, ilgili kontrolün yanında belirtin. Sayfa, bölüm, satır, boş durum ve iletişim kutusu açıklamalarında tekrarlamayın.
• Bariz bir eylemi açıklayan bir paragraf yerine kesin bir etiket veya örnek tercih edin. "Başlamak için bir tane oluşturun", "Aşağıya tıklayın" veya "Bunu daha sonra değiştirebilirsiniz" gibi genel talimatlardan, gerçek bir belirsizliği gidermedikçe kaçının.
• İzinleri, maliyeti, yıkıcı sonuçları, yürütme ön koşullarını, girdi kısıtlamalarını ve hata kurtarmayı ilgili olduğunda görünür tutun. Bunları yalnızca üzerine gelince görünen yardımda saklamayın.
• Tanıtıcı rehberliği yalnızca gerektiği yerde gösterin. İleri düzey kullanımı ve tanılamayı varsayılan sayfa gövdesi yerine açık, erişilebilir yardıma koyun.
• Girdi etiketlerini, erişilebilir adları ve gerekli açıklama ilişkilendirmelerini koruyun. Gereksiz görünür metni toptan yalnızca ekran okuyucuya yönelik metne taşımayın.
• İngilizce ve çevrilmiş metni, mobilin bağımsız dizeleri dahil, birlikte inceleyin. PR incelemesinde eklenen bilgiyi, aynı ekrandaki tekrarı, görüntülenme koşullarını ve korunan kısıtlamaları kontrol edin. Uzunluk bir inceleme sinyalidir, otomatik bir silme kuralı değil.

Paylaşımlı ayar bileşenleri isteğe bağlı açıklamaları zaten kabul eder. Örnekler ve yeni çağrı yerleri, gerekçesi olmadıkça bunları atlamalıdır; zorunlu açıklama prop'ları veya ayrı bir metin politikası eklemeyin.

Şüphede kaldığınızda nereye bakmalı

Sözlük bir terimi kapsamıyorsa, şunlara bakın:

1. apps/docs/content/docs/*.zh.mdx — fiili Çince üslup standardı, 20'den fazla sayfada tutarlı çeviri
2. packages/views/locales/zh-Hans/auth.json ve editor.json — JSON yapısı + seçici API kalıpları
3. packages/views/auth/login-page.tsx — bileşen düzeyinde seçici API çağrı sitesi
4. packages/views/settings/components/preferences-tab.tsx — dil seçici referansı

Bu sayfayı güncelleme

Burada bir kuralı değiştirirseniz, ayrıca:

1. İlgili locale JSON'larında / AGENTS.md'de / dokümanlar sayfasında uygulayın
2. İnceleyicilerin sonraki taramayı aramasını bilmesi için PR açıklamasında değişikliği not edin

Bu sayfa sözleşmedir; başka hiçbir şey onu geçersiz kılmaz.