dbn-localization-guide

# DBN Localization Guide ## Scope Use this skill for localization-only or localization-heavy changes in DBN. Pair it with `dbn-translation-guide` when translating or reviewing wording, maintaining locale glossaries, or checking terminology consistency. Pair it with `dbn-codebase-guide` only when the task also needs broader architecture, service, UI, or persistence guidance. Keep localization edits narrowly scoped. Do not refactor unrelated code while replacing hardcoded strings. Before changing Java, XML, `.form`, or resource files, inspect enough context to identify open points. Proceed directly for straightforward localized fixes. Ask for confirmation before broad NLS cleanup, key renames, visible wording changes, `.form` rewiring, or changes where callers/composition are unclear. ## Resource Access - Resource bundle: `src/main/resources/messages/DBNResources.properties`. - Access localized text with `import static com.dbn.nls.NlsResources.txt;`. - Code should call `txt(...)` directly. Do not introduce wrapper helpers around `NlsResources`. - Text templates live under `src/main/resources/textTemplates`, mirroring the Java package of the lookup class. - Load user-visible, localizable templates with `TextResources.getLocalizable(...)`. Load internal prompts, model instructions, generated syntax, and other non-user-visible templates with `TextResources.getInternal(...)` and mark the resource name/content `@NonNls`. - IntelliJ intention descriptions live under `src/main/resources/intentionDescriptions/<IntentionClassSimpleName>/description.html`; bundled translations use sibling files such as `description_de.html`, `description_ja.html`, and every standalone HTML file should declare a matching `<html lang="...">`. - IntelliJ intention categories in `plugin.xml` should use `<categoryKey>` rather than literal `<category>` when they are plugin-provided. `categoryKey` resolves against the plugin-level `<resource-bundle>` by default. Prefer one DBN-style key per complete category path, using `app.<component>.category.<Title>`, and put any hierarchy slash in the translated value, for example `Database/Statement execution`; the platform resolves the key first, then splits the value into category path segments. - IntelliJ intention before/after examples are code samples, not prose translations. Keep them only when they are real examples using the platform naming pattern `before.<language-extension>.template` / `after.<language-extension>.template`; otherwise set `<skipBeforeAfter>true</skipBeforeAfter>` on the `intentionAction` in `plugin.xml`. - File-template description HTML lives under `src/main/resources/fileTemplates/*.html`. Treat visible description prose there as localizable content when translations are added, and keep standalone HTML metadata such as `lang` valid. - Prefer passing translated text into constructors/APIs. Pass keys only when the callee explicitly expects keys. - Use `@Nls` for localized text values and `@NonNls` for internal strings such as SQL, code, model prompts, file paths, IDs, log-only text, wire protocols, and generated syntax. - Do not put executable code snippets, SQL/PLSQL blocks, generated syntax, or protocol payloads in resource bundles. Keep them as `@NonNls` code constants/helpers and set UI fields from code. - Use `@PropertyKey` only for APIs that intentionally accept resource keys. - For `.form` files, use `resource-bundle="messages/DBNResources"` and a `key`. - Use DBN `Messages`, `Dialogs`, and `MessageBundle` helpers for user-facing notifications and dialogs. ## Key Families Choose the family from the functional context, not from the Java class or form name: - `app.<area>.*`: runtime UI text, actions, labels, columns, placeholders, titles, tooltips, constants. - `cfg.<area>.*`: settings, configuration forms, setup wizards, configuration constants and hints. - `msg.<area>.*`: dialogs, questions, errors, warnings, info messages, dialog buttons and titles. - `ntf.<area>.*`: notification titles, bodies, links, and actions. - `prc.<area>.*`: progress/process titles and body text. - `log.<area>.*`: only for user-facing log output. Do not localize ordinary diagnostic logger strings unless requested. Use shared groups (`app.shared.*`, `msg.shared.*`) only for genuinely reusable wording. ## Key Shape Use `<family>.<area>.<element>.<Name>`. - `area` is the functional area, for example `assistant`, `connection`, `debugger`, `data`, `java`, `mcp`, `languageParser`, or `vector`. - `element` describes the role of the string, not the Swing class by itself. - `Name` should be stable and concise. Do not encode an entire long sentence into the key token; use a short semantic token such as `ServerNameHint`. Keep new keys in the associated resource group and preserve sorted order within that group. ## Element Types - `action`: visible action text or menu item text. - `tooltip`: action descriptions and UI tooltip text. IntelliJ action descriptions are tooltips. - `button`: `JButton` text and dialog/action button captions. - `intention`: IntelliJ intention and quick-fix names returned by APIs such as `EditorIntentionAction#getText()` or `LocalQuickFix#getName()`. - `label`: short JLabel/check box/radio button captions that behave like labels. - `text`: sentence-like labels, explanatory text, status text, HTML bodies, and longer UI copy. - `title`: dialog, popup, panel, group, message, or progress titles. - `column`: `TableModel.getColumnName(...)` values. - `placeholder`: placeholder/sentinel display values such as `[title]`, `<all>`, `[UNDEFINED]`. - `const`: enum/presentable constants and option names. - `token`: reusable sentence fragments or domain words inserted into other messages. - `aria`: accessibility names/descriptions. - `url`: localized hyperlink targets, documentation pages, API pages, and other URLs that may differ by locale. - `hint`, `link`, `question`, `info`, `warning`, `error`: use when the role is more specific, especially under `cfg.*` and `msg.*`. If a label is a full sentence or instruction, prefer `text` over `label`. Check boxes and radio buttons can still use `label` when they are short control captions. ## Common Patterns - Progress operations usually have paired keys: - `prc.<area>.title.<Operation>` - `prc.<area>.text.<Operation>` - Parser display keys use the functional area `languageParser`, for example `msg.languageParser.token.*` and `msg.languageParser.tokenCategory.*`. - Table model column names use `app.<area>.column.<Name>`. - Presentable enums use `app.<area>.const.<EnumName_VALUE>` or `cfg.<area>.const.<EnumName_VALUE>`, depending on runtime versus configuration context. - Runtime action keys use `app.<area>.action.<Name>`. For `AnAction` classes whose plugin XML text is only a keymap/context caption, set the template presentation from code using DBN keys and keep runtime update text unprefixed when needed. - Editor intention keys use `app.<area>.intention.<Name>`. Do not reuse `.action.` keys for `EditorIntentionAction#getText()` just because an intention invokes the same behavior as a menu or toolbar action. - Do not touch `plugin.xml` unless explicitly requested. When action descriptions are localized in code, use `.tooltip.` keys. - For strings inserted into composed sentences, use `.token.` rather than `.action.` or `.label.`. ## Text Values - Preserve current visible wording unless the user asks for wording or capitalization changes. - Prefer parameterized resource values over concatenation: - Good: `txt("prc.object.text.CreatingObjectDescription", description)` - Avoid: `"Creating " + description` - Use `MessageFormat` choice patterns for visible singular/plural text when useful. - Preserve mnemonic markers (`&`) in form labels and button text when the ampersand marks a keyboard mnemonic, for example `&Name` or `Na&me`. - Do not treat textual ampersands as mnemonics. If the unqualified base value uses ` & ` to mean "and", replace it in the base value with `and` unless it is part of an official product name or literal. Localized values should translate the word naturally and should not gain a mnemonic marker. - Newline and HTML values belong in the properties file with escaped `\n` or existing HTML formatting. - Use separate `link` and `url` keys when a localized link caption can point to a locale-specific target, for example `cfg.assistant.link.SelectAiDocs` plus `cfg.assistant.url.SelectAiDocs`. - Product names, provider names, SQL keywords, API literals, generated code, and model prompts are often `@NonNls`, not resource keys. ## Translation Handoff For translation wording, glossary decisions, batch semantics, stale-English scans, and reviewer caveats, use `dbn-translation-guide`. This localization skill still owns the DBN mechanics: - Use only the unqualified base resources as the source of truth for locale variants. - Prefer generic language locale files for broadly applicable translations, for example `DBNResources_de.properties` and `*_de.html.ft`. Use region-qualified variants such as `_de_DE` only for regional overrides. - Translate only localizable text templates, currently user-visible `*.html.ft` files loaded through `TextResources.getLocalizable(...)`, IntelliJ intention `description.html` files, and user-visible file-template description HTML. Do not create locale variants for internal `*.md.ft` prompt/instruction templates loaded through `TextResources.getInternal(...)` or for intention before/after code examples. - Preserve every resource key unless the task explicitly adds, removes, or renames keys. - Preserve technical literals and placeholders exactly: `{0}`, MessageFormat choice patterns, escaped `\n`, HTML tags, mnemonic markers (`&Name`, `Na&me`), SQL/API/class names, file names, and protocol literals. - Do not duplicate non-localizable code snippets into localized bundles. If a key family like `.code.` appears, inspect the caller and move the snippet to `@NonNls` code instead of translating it. ## UI Writing Rules - Use casing from `Sentence vs. Title Case`: commands and true headers normally use title capitalization, while sentence-like labels, descriptions, tooltips, and messages normally use sentence capitalization. - Keep UI text short and clear: present tense, one idea per sentence, active voice, user-perspective wording, and no unnecessary generic words. - Use ellipsis only for actions that open input-capable dialogs, truncated text without a scrollbar, or ongoing progress text. - Do not end a single sentence or IDE action with a period. Use periods between multiple sentences. - Use question marks only for confirmation alerts. Do not use exclamation points. - Inspection NLS should be short, sentence-cased, problem-focused, and specific. Descriptions should start with a verb such as `Reports`. ## Verification Passes Use verification passes for broad resource-file cleanup. Keep each pass focused on one rule, and re-scan after editing. ### Batch Verification Gate Run these checks for every translated batch before moving to the next batch. - Key parity: the locale bundle must have the same key set as the unqualified source bundle unless the task explicitly adds or removes keys. - Placeholder and marker parity: every `{0}`, `{1}`, MessageFormat choice/plural pattern, escaped newline, HTML boundary, mnemonic marker, and quoted technical literal must be preserved or intentionally changed with caller inspection. Do not count textual ` & ` as a mnemonic. - Source capitalization check: compare each translated value against the unqualified source value. For standalone roles such as `action`, `button`, `title`, `column`, `error`, `warning`, `info`, `message`, `question`, `aria`, user-facing `text`, progress, notification, and log lines, review any value where the source starts with an uppercase letter but the translation starts lowercase. Treat inserted fragments, `token`, `const`, `unit`, `placeholder`, object type names, URLs, and code-like values as exceptions only after classification. - Role capitalization check: independently scan translated `title`, `error`, `warning`, `info`, `question`, `message`, progress, notification, and log values for lowercase sentence starts. Fix full-sentence and standalone values; leave lowercase fragments only when they are intentionally composed into another sentence. - Textual ampersand check: scan the unqualified base bundle for prose ` & `. Replace it with `and` unless it is part of an official product name or literal. Do not make localized values preserve a textual ampersand as a mnemonic marker. - Diff check: run `git diff --check` for the touched locale files after each substantial batch. - For stale-English, glossary consistency, semantic ambiguity, and UI role checks, use `dbn-translation-guide`. Useful starting checks: ```bash ruby -e 'loc=ARGV.fetch(0); base={}; File.readlines("src/main/resources/messages/DBNResources.properties", chomp:true).each{|l| next if l.strip.empty? || l.start_with?("#"); k,v=l.split("=",2); base[k]=v if v}; File.readlines(loc, chomp:true).each_with_index{|l,i| next if l.strip.empty? || l.start_with?("#"); k,v=l.split("=",2); next unless v && base[k]; b=base[k].sub(/^\\ /,"").sub(/^\\ - /,""); f=v.sub(/^\\ /,"").sub(/^\\ - /,""); next unless b =~ /\A[A-Z]/ && f =~ /\A[[:lower:]]/; role=k.split(".")[2] || ""; next if %w[const token unit placeholder].include?(role); puts "#{i+1}:#{k}=#{v} [base=#{base[k]}]"}' src/main/resources/messages/DBNResources_fr.properties ruby -e 'def load(path); h={}; File.readlines(path, chomp:true).each{|l| next if l.strip.empty? || l.start_with?("#"); k,v=l.split("=",2); h[k]=v if v}; h; end; base=load("src/main/resources/messages/DBNResources.properties"); loc=load(ARGV.fetch(0)); missing=base.keys-loc.keys; extra=loc.keys-base.keys; bad=[]; base.each{|k,bv| next unless loc[k]; bp=bv.scan(/\{[0-9]+(?:,[^{}]+)?\}/).sort; fp=loc[k].scan(/\{[0-9]+(?:,[^{}]+)?\}/).sort; bad << [k,bp,fp] if bp!=fp}; puts "missing=#{missing.size} extra=#{extra.size} placeholder_mismatches=#{bad.size}"; bad.first(20).each{|k,bp,fp| puts "#{k}: #{bp.inspect} != #{fp.inspect}"}' src/main/resources/messages/DBNResources_fr.properties ``` ### Placeholder and MessageFormat Safety - Preserve every `{0}` / `{1}` placeholder, MessageFormat choice/plural pattern, escaped newline (`\n`), and HTML boundary unless the caller is changed at the same time. - Compare old and new placeholder sets for every changed resource value. Treat any mismatch as a blocker until the Java/.form caller is inspected. - Do not add unnecessary escapes for double quotes in `.properties` values. Use `"{0}"`, not `\"{0}\"`, unless the visible text really needs a backslash. - Be careful with apostrophes in MessageFormat values: a single quote starts/ends quoting, and a literal apostrophe usually needs to be doubled. SQL/code snippets may already use doubled quotes intentionally. - For values ending with or containing `\n`, inspect the caller before removing or moving the newline. Some dialog text depends on resource-level spacing, while other code adds the newline itself. Useful check: ```bash rg -n '\{[0-9]' src/main/resources/messages/DBNResources.properties ``` After editing a broad set of values, derive changed keys from `git diff -U0` and compare placeholder sets for old and new values before compiling. ### Key Family and Usage Context - Verify key family from the display context, not from the class name. The same concept can be `app.*` in runtime UI, `cfg.*` in settings, `msg.*` in a dialog body/title, `ntf.*` in a notification, and `prc.*` in progress text. - Check exact usages before renaming or moving keys. Do not infer from the key name alone, especially when the value is used by an action, intention, notification, progress task, or form label. - When renaming keys, update Java, `.form`, and resource references together, then re-run `rg` for every old key and old visible value. - Keep moved or renamed keys sorted within their resource group after editing. - Allow casing to differ by usage space: a menu/action can be title-cased while an intention, hint, notification body, or configuration label should usually be sentence-cased. Useful check: ```bash rg -n 'txt\("([^"]+)"' src/main/java ``` ### Required and Missing Wording - For validation messages, prefer direct remediation over passive failure labels: `Enter a credential name`, `Select a database file`, `Specify a JDBC driver`, `Configure a schema`. - Use `Enter` for typed values, `Select` for choices/files/schemas, `Specify` for named configuration values, and `Configure` when the user must open or adjust settings. - Avoid unnecessary `required`, `missing`, `not specified`, and `cannot be empty` wording when a direct action is clearer. - Keep composite-message use cases in mind. Direct imperative messages work well in cumulative lists such as `Correct the following errors:\n - Enter a data type`, but sentence fragments may not.