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 /{isim}/{fiil} 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}/{bölüm} 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.

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: <dosya>.test.ts(x) olarak yan yana
• Store'lar (Zustand): <özellik>-store.ts, use<Ozellik>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: <tablo>_id
• Boolean'lar: is_<durum> veya <durum>_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

Go

• Standart gofmt + go vet. İstisna yok.
• İşleyici dosyaları alanı yansıtır: agent.go, auth.go, runtime.go
• Testler: <dosya>_test.go yan yana
• İşleyicilerde UUID ayrıştırma için, kök CLAUDE.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ı: <özellik>/queries.ts'de fabrika fonksiyonları, örn. issueKeys.detail(id).

İş 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

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ı. "输入任务标题...".

Şü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 / CLAUDE.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.