i18n & Diagnostic Templates

Internationalization and diagnostic template features introduced in v1.1.0

---

i18n — Internationalization

Kafka Log Analyzer supports English and Chinese out of the box. All user-visible strings (CLI messages, MCP tool descriptions, report headings, chart labels, error messages, and template names) go through the t() function.

Setting the Language

Priority order:

1. LOCALE environment variable
2. --locale / -l CLI flag
3. LC_ALL / LC_MESSAGES / LANG system locale (contains zh → Chinese)
4. Default: en

CLI examples:

# Use Chinese
npx kafka-log-analyze analyze server.log --locale zh

# Or via environment variable
LOCALE=zh npx kafka-log-analyze analyze server.log

# Short flag
npx kafka-log-analyze analyze server.log -l zh

Architecture

src/i18n/
├── index.ts    # t(), setLocale(), getLocale()
├── en.ts       # ~180 English keys
└── zh.ts       # Chinese translations

• t(key, params?) — translate a key with optional {param} substitution
• setLocale(locale) — set active locale (call once at startup)
• getLocale() — get current locale
• resetLocale() — reset to detected default (for testing)

No runtime hot-swap — locale is locked at process start.

---

ASCII Timeline Chart

The analyzer renders an ASCII stacked bar chart for timeline distribution:

14:30 ████████████████████·····░░░░░░░░░░░░░░░ 102
14:35 ████████········░░░░░░░░░░░░░░░░░░░░░░░░  67
       █ Critical  · Warning  ░ Info  |  Total: 169  Errors: 7  Warns: 35

Sparkline for Push Notifications

A single-line mini chart using Unicode block elements is embedded in Feishu and Slack push messages:

📈 ▂▃▅█▇▅▃▂▁▂▃▅▆█▇▅▃▂

MCP Tool Option

The analyze_log tool accepts a chart boolean parameter (default true) to include or exclude the chart from reports.

---

Shell Completion

Generate shell completion scripts covering all commands, flags, and enum values:

# bash
npx kafka-log-analyze completion bash > /etc/bash_completion.d/kafka-log-analyze
source ~/.bashrc

# zsh
npx kafka-log-analyze completion zsh > "${fpath[1]}/_kafka-log-analyze"
autoload -U compinit && compinit

# fish
npx kafka-log-analyze completion fish > ~/.config/fish/completions/kafka-log-analyzer.fish

Completion covers:

• All commands and subcommands
• --focus values: producer, consumer, broker, lag, error
• --timeline values: 1m, 5m, 15m, 1h, 6h, 1d
• --report values: markdown, json, slack, folded-markdown
• --priority values: P0, P1, P2, P3

---

Folded Markdown Reports

New --report folded-markdown format generates collapsible reports:

# Kafka Log Analysis Report

## Summary
- **Total Events**: 1024
- **Anomalies Found**: 3

<details>
<summary>📊 By Priority (click to expand)</summary>

| Priority | Count | Description |
|----------|-------|-------------|
| P0       |     2 | Critical - Cluster down, data loss risk |
...

</details>

<details>
<summary>⚠️ Anomalies Detected (3)</summary>

#### 1. Consumer Lag Spike (P1)
...

</details>

Ideal for GitHub issues, Slack snippets, and any Markdown renderer that supports <details>.

---

Interactive TUI Browser

Use --interactive / -i to launch a keyboard-driven terminal UI:

npx kafka-log-analyze analyze server.log --interactive

Controls:

Key	Action
↑ / ↓	Navigate sections
Enter / Space	Toggle expand/collapse
e	Expand all sections
c	Collapse all sections
q	Quit

The TUI uses pure readline — no blessed or ink dependency.

---

Diagnostic Templates

Built-in Templates

ID	Name	Focus	Priority Hint
lag-diagnosis	Lag Diagnosis	consumer, lag	P0, P1
rebalance-storm	Rebalance Storm Investigation	consumer	P0, P1, P2
producer-errors	Producer Error Analysis	producer, error	P0, P1
broker-health	Broker Health Check	broker	P0, P1, P2
full-audit	Full Audit	(all)	(all)

CLI Usage

# List available templates
npx kafka-log-analyze templates

# Use a template
npx kafka-log-analyze analyze server.log --template lag-diagnosis

# Template with overrides (CLI flags take precedence)
npx kafka-log-analyze analyze server.log --template lag-diagnosis --focus producer

MCP Tools

diagnose — Run a diagnostic template:

{
  "tool": "diagnose",
  "input": {
    "template_id": "lag-diagnosis",
    "source": "file",
    "path": "/var/log/kafka/server.log",
    "report": "folded-markdown"
  }
}

list_templates — List templates with smart ranking:

{
  "tool": "list_templates",
  "input": {
    "cluster": "production"
  }
}

Templates are ranked by historical anomaly frequency for the specified cluster. Without a cluster or history, returns all templates in default order.

Smart Template Recommendation

The recommendTemplates() function queries the SQLite database for recent anomaly patterns and scores each template by how many of its target anomaly types appear in history. For example, if lag_spike anomalies dominate recent history, the lag-diagnosis template ranks first.

---

Related Documentation

• Command Reference — Complete CLI command reference
• Configuration — Environment variables including LOCALE
• API Reference — MCP Tools API including diagnose and list_templates