hana-developer-cli-tool-example translatable-text-handling.instructions.md

Translatable Text Handling Guidelines

Use this guide whenever you add, update, or reference user-facing text strings in CLI commands, API routes, utilities, or any user-visible output.

Core Principle

All user-facing text must be translatable. Never hardcode strings that users see. Always use bundle.getText(key) to retrieve text from the appropriate i18n properties file.

When to Translate

✅ Always translate:

• Command descriptions (describe)
• Option and parameter descriptions
• Help text and error messages
• Console output, responses, and logging for end-users
• UI labels and status messages
• Validation error messages
• Success/warning/info messages

❌ Do NOT translate (keep as inline strings):

• Internal debug messages (prefixed with debug())
• File paths and system constants
• Technical identifiers (command names, option names)
• Variable names and code structure
• JSON keys and data structure identifiers

Example: What to Translate vs. What Not To

// ✅ CORRECT: User-facing text is translatable
export const describe = bundle.getText("backupCommand")  // "Create a database backup"
export const builder = (yargs) => yargs
  .option('schema', {
    describe: bundle.getText("backupSchema"),  // "Target schema for backup"
    type: 'string'
  })
  .example('hana-cli backup full', bundle.getText("backupExampleFull"))

// ❌ INCORRECT: Hardcoded strings not translatable
export const describe = "Create a database backup"  
export const describe = `Show ${tableName} schema`  // Dynamic content hardcoded

// ✅ CORRECT: Dynamic content with translation
const message = bundle.getText("backupComplete", { schema: schemaName })
// key: "backupComplete=Backup completed for schema {0}"

Import Pattern

Always import bundle from the correct base utility. The import source depends on your module type:

For CLI Commands (bin/*.js)

// In command setup (synchronous context):
import * as baseLite from '../utils/base-lite.js'
export const describe = baseLite.bundle.getText("commandKey")

// In async handler or functions:
const base = await import('../utils/base.js')
const message = base.bundle.getText("messageKey")