I18n UI Text

Writing UI Text

This skill is about what the strings say, not how they're wired up. For the JSON message format, key naming, pluralization/variants, and the generated Language Pack facade (m.*) and runtime, use the inlang-i18n skill. Use the two together: inlang-i18n for the file shape, this skill for the words inside it.

When this applies

Any English string a user will read inside Obsidian:

• Command names registered via plugin.addCommand({ name: ... })
• Setting labels and descriptions (new Setting(...).setName(...).setDesc(...))
• Button labels (.setButtonText(...), .setCta())
• Notices (new Notice(...))
• Modal titles and body text
• Menu item titles
• Status bar text, ribbon tooltips, dropdown options
• Error and validation messages shown to the user

All of these should be authored in messages/en.json (the base locale) per the inlang-i18n skill, then translated. The base-locale string is the authoritative source — get the English right first.

Internal logs, code comments, and developer-only diagnostics are not UI text and don't follow this guide. Those go through LogTape (see AGENTS.md → Logging).

How to use this skill

1. Draft the string.
2. Run through the quick checklist below — most copy issues are caught here.
3. If anything is ambiguous (a term you're unsure about, an unusual interaction phrasing, OS-shortcut formatting, em-dash placement), consult the Terminology and Grammar section inlined below.
4. For long-form copy (multi-paragraph modal text, onboarding flows) or doc-like content, also consult references/obsidian-style-guide.md for sections on lists vs. prose, callouts, and information structure. Those sections target docs but apply when UI copy gets long.

Quick checklist for UI strings

Before committing a new string, verify:

• Sentence case — "Refresh Zotero database", not "Refresh Zotero Database". Capitalize only the first word and proper nouns. Applies to command names, button labels, setting names, headings, modal titles.
• Imperative verb for actions — commands and buttons that perform something start with a verb: "Import notes", "Open library", not "Importing notes" or "Library import".
• "Select", not "click" or "tap" — when copy refers to an action the user takes on UI (e.g., setting descriptions saying "Select a folder to…").
• American English — organize, color, behavior, synchronize. Not organise, colour, behaviour, synchronise.
• Plain, global English — no idioms, no jargon when a common word works. Active voice.
• Match Obsidian's noun choices — "note" (for .md files in the vault), "file" (other extensions), "folder" (not "directory"), "sidebar" (not "side bar"), "keyboard shortcut" (not "hotkey"), "heading" (not "header"), "sync"/"syncing" (not "synchronize"/"synchronizing"), "search term" (not "search query"), "active note" (not "current note"), "note name" (not "note title"), "file type" (not "file format"), "maximum"/"minimum" (not "max"/"min"), "perform" (not "invoke"/"execute").
• Product names — Obsidian products start with "Obsidian": "Obsidian Sync", "Obsidian Publish". Zotero is "Zotero" (proper noun, no prefix).
• Sequential UI navigation uses → — "Settings → Community plugins" with the actual arrow character (U+2192), not -> or >.
• Bold button references in prose — when a setting description refers to a button, the button name is bold in Markdown-rendered contexts. (Plain Obsidian Setting descriptions render limited Markdown; check before relying on it.)
• Keyboard shortcuts use Ctrl+Z / Command+Z — no spaces around +, no Cmd/Ctrl+Z shorthand. Specify both OSes when they differ.
• Realistic examples — not foo/bar. Use plausible Zotero items, collection names, citation keys.
• No trailing period on short labels — button labels, command names, setting names omit the period. Multi-sentence descriptions and notices use full punctuation.
• No directional anchoring for settings — don't say "to the right of X, select Y"; settings re-flow by device. Say "Next to X, select Y." Use "above"/"below" for vertical relationships, not "up"/"down".
• Don't echo the key into the value — message key database.refresh.success with value "Database refreshed" is fine; value of "database.refresh.success" is a leak.

Terminology and Grammar

Inlined from the Obsidian Style Guide. The full upstream guide is in references/obsidian-style-guide.md.

Language Style

For English documentation, use Global English to serve a worldwide audience:

• Avoid idioms and culturally-specific expressions
• Use active voice and direct sentence construction
• Prefer simple, common words over complex terminology
• Be explicit rather than implied
• Use American English spelling (e.g., 'organize' not 'organise')

Terms

• Prefer "keyboard shortcut" over "hotkey"
• Prefer "the Obsidian app" on mobile, "the Obsidian application" on desktop
• Prefer "sync" or "syncing" over "synchronise" or "synchronising"
• Prefer "search term" over "search query"
• Prefer "heading" over "header"
• Prefer "maximum" over "max" and "minimum" over "min"

Product Names

Obsidian product names start with "Obsidian," such as "Obsidian Publish" and "Obsidian Sync." Use short forms in subsequent references if paragraphs become repetitive.

UI and Interactions

• Use bold for button text
• Prefer "select" over "tap" or "click" (except mobile-specific instructions)
• Prefer "sidebar" over "side bar"
• Prefer "perform" over "invoke" or "execute"
• Use → (U+2192) symbol for sequential interactions: "Settings → Community plugins"

Notes, Files, and Folders

• Use "note" for Markdown files in the vault
• Use "file" for other file extensions
• Prefer "note name" over "note title"
• Prefer "active note" over "current note"
• Prefer "folder" over "directory"
• Prefer "file type" over "file format"

Use "open" when the destination note is hidden; use "switch" when both source and destination are open in separate splits.

Reference Documentation for Settings

Document settings within Obsidian when possible. Avoid external documentation unless:

• More in-depth knowledge is required
• The setting is commonly misused or questioned
• It drastically changes user experience