跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
数据与分析

frappe-core-translation

Use when implementing translations/i18n in Frappe v14-v16 apps. Covers _() in Python, __() in JavaScript, CSV translation files, bench commands, string extraction rules, lazy translation _lt(), PO/MO files [v15+], RTL support, and custom app translations. Prevents common mistakes with f-strings, concatenation, and template literals that break string extraction. Keywords: translation, i18n, _(), __(), _lt(), CSV, PO, gettext,, translate my app, multi-language, text not translated, wrong language, how to add translation. bench get-untranslated, RTL, localization.

OpenAEC-Foundation · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add Impertio-Studio/Frappe_Claude_Skill_Package --skill frappe-core-translation

技能说明


name: frappe-core-translation description: > Use when implementing translations/i18n in Frappe v14-v16 apps. Covers _() in Python, __() in JavaScript, CSV translation files, bench commands, string extraction rules, lazy translation _lt(), PO/MO files [v15+], RTL support, and custom app translations. Prevents common mistakes with f-strings, concatenation, and template literals that break string extraction. Keywords: translation, i18n, _(), __(), _lt(), CSV, PO, gettext,, translate my app, multi-language, text not translated, wrong language, how to add translation. bench get-untranslated, RTL, localization. license: MIT compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16." metadata: author: OpenAEC-Foundation version: "3.0"

Frappe Translation / i18n

Deterministic patterns for translating Frappe apps across v14, v15, and v16.


Quick Reference

TaskPythonJavaScript
Translate string_("Hello")__("Hello")
With substitution_("Hello {0}").format(name)__("Hello {0}", [name])
With context_("Change", context="Coins")__("Change", null, "Coins")
Lazy (module-level)_lt("Pending") [v15+]N/A
Check RTLfrappe.utils.is_rtl()frappe.utils.is_rtl()

Decision Tree

Need to translate a string?
├── In Python (.py)?
│   ├── Inside a function/method → _("text {0}").format(val)
│   ├── Module-level constant [v15+] → _lt("text")
│   └── Module-level constant [v14] → define inside function or use lazy
├── In JavaScript (.js)?
│   └── ALWAYS → __("text {0}", [val])
├── In Jinja template (.html)?
│   └── {{ _("text") }}
├── In Vue (.vue)?
│   └── __("text") in <script>, {{ __("text") }} in <template>
└── DocType label/description/option?
    └── Auto-extracted — no _() needed

Where do translations live?
├── v14 → apps/{app}/{app}/translations/{lang}.csv
├── v15+ → apps/{app}/{app}/locale/{lang}/LC_MESSAGES/{app}.po
└── User overrides → Translation DocType (highest priority)

Need to extract untranslated strings?
├── v14 → bench --site {site} get-untranslated {lang} {output}
└── v15+ → bench generate-pot-file --app {app}

Translation Priority (Highest First)

PrioritySourceScope
1Translation DocType (user overrides)Per-site
2MO files (locale/{lang}/.../{app}.mo)Per-app [v15+]
3CSV files (translations/{lang}.csv)Per-app
4Parent language (e.g., pt for pt-BR)Fallback

Version Differences

Featurev14v15v16
_() / __()YesYesYes
_lt() lazy translationNoYesYes
CSV translationsYesYes (legacy)Yes (legacy)
PO/MO (gettext)NoYesYes
bench generate-pot-fileNoYesYes
Babel JS extractorNoYesYes
Type hints on _()NoNoYes

Auto-Extracted Strings (No _() Needed)

These are extracted automatically by the framework:

  • DocType labels and descriptions
  • Select field options (each option line)
  • Workflow states and actions
  • Print Format labels
  • Report column labels
  • Notification subjects (not body)
  • Dashboard chart labels

String Extraction Rules

File TypeExtractorWhat It Finds
.pyBabel (AST)_("..."), _lt("...") calls
.jsBabel tokenizer [v15+] / regex [v14]__("...") calls
.htmlRegex{{ _("...") }} in Jinja
.vueSame as JS__("...") in script/template
.jsonDocType parserLabels, descriptions, options

CRITICAL: Extractors work on the AST/tokens. They CANNOT extract dynamically constructed strings. See Anti-Patterns.


Anti-Patterns (NEVER Do These)

PatternWhy It BreaksCorrect Form
_(f"Hello {name}")f-string not extractable_("Hello {0}").format(name)
_("Hello " + name)Concatenation fragments_("Hello {0}").format(name)
_("Welcome %s") % nameOld-style not extractable_("Welcome {0}").format(name)
__(`Hello ${name}`)Template literal not extractable__("Hello {0}", [name])
_(" Hello ")Leading/trailing spaces trimmed_("Hello")
_("item" if x else "items")Ternary inside _()_("item") if x else _("items")
_(variable)Variable not extractable_("Known String")

Full anti-pattern catalog with code examples: references/anti-patterns.md


CSV Translation File Format

Location: apps/{app}/{app}/translations/{lang}.csv

"source","translation","context"
"Hello","Hallo",""
"Change","Wisselgeld","Coins"
"Change","Wijziging","Amendment"
  • ALWAYS use UTF-8 encoding (no BOM)
  • ALWAYS quote all fields with double quotes
  • Context column is optional but MUST be present (empty string if unused)
  • No hooks registration needed — auto-discovered from translations/ directory

PO/MO Files [v15+]

Location: apps/{app}/{app}/locale/{lang}/LC_MESSAGES/{app}.po

# Generate POT template
bench generate-pot-file --app {app}

# Migrate existing CSV to PO
bench migrate-csv-to-po --app {app}

# Compile PO to MO (required for runtime)
bench compile-po-to-mo --app {app}

PO files follow standard GNU gettext format. Use any PO editor (Poedit, Weblate, Transifex).


Bench Commands

CommandVersionPurpose
bench --site {site} get-untranslated {lang} {output.csv}AllExport untranslated strings
bench update-translations {lang} {untranslated.csv} {translated.csv}AllImport translations
bench generate-pot-file --app {app}v15+Generate .pot template
bench migrate-csv-to-po --app {app}v15+Convert CSV to PO format
阅读完整来源 ↗