♻️ refactor(i18n): replace kebab-case with snake_case in FTL keys

itisnotyourenv · claude · itisnotyourenv · commit 59d0f6bdb88e · 2026-02-24T03:00:41.000+03:00
- Rename all locale keys from kebab-case to snake_case across en/ and ru/
- Add separator="_" to TranslatorHub so typed method calls match FTL keys
- Introduce types.py with TYPE_CHECKING guard for typed TranslatorRunner
- Migrate routers to use typed i18n method calls where applicable
- Unify TranslatorRunner imports to src.infrastructure.i18n
- Remove obsolete stubs.pyi (replaced by types.py)
- Update generate_i18n_stubs.py to target types.py
- Add generate-i18n justfile command

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/justfile b/justfile
@@ -64,4 +64,8 @@ test-db-up:
 
 lint:
     uv run ruff format src tests
-    uv run ruff check src tests --fix
+    uv run ruff check src tests --fix
+
+generate-i18n:
+    uv run python scripts/generate_i18n_stubs.py
+    uv run ruff format src/infrastructure/i18n/types.py
diff --git a/locales/en/admin.ftl b/locales/en/admin.ftl
@@ -1,3 +1,3 @@
 # Admin-only messages
-example-executed = Example admin command executed
-bot-started = Bot has started!
+example_executed = Example admin command executed
+bot_started = Bot has started!
diff --git a/locales/en/common.ftl b/locales/en/common.ftl
@@ -1,2 +1,2 @@
 # Common strings shared across features
-echo-unknown-message = I don't understand this message. Use /start to begin.
+echo_unknown_message = I don't understand this message. Use /start to begin.
diff --git a/locales/en/settings.ftl b/locales/en/settings.ftl
@@ -1,18 +1,18 @@
 # Settings messages
-settings-title = ⚙️ Settings
+settings_title = ⚙️ Settings
 
     Choose an option:
-settings-language-title = 🌐 Language
+settings_language_title = 🌐 Language
 
     Select your preferred language:
-settings-language-changed = ✅ Language changed successfully.
+settings_language_changed = ✅ Language changed successfully.
 
 # Onboarding
-onboarding-language = 🌐 Please select your language:
+onboarding_language = 🌐 Please select your language:
 
 # Buttons
-btn-language = 🌐 Language
-btn-settings = ⚙️ Settings
-btn-back = ↩️ Back
-lang-en = 🇬🇧 English
-lang-ru = 🇷🇺 Русский
+btn_language = 🌐 Language
+btn_settings = ⚙️ Settings
+btn_back = ↩️ Back
+lang_en = 🇬🇧 English
+lang_ru = 🇷🇺 Русский
diff --git a/locales/en/stats.ftl b/locales/en/stats.ftl
@@ -1,20 +1,20 @@
-stats-overview =
+stats_overview =
     📊 Statistics
 
     Total users: { $total }
     Referred: { $referred } ({ $referred_pct }%)
     Organic: { $organic } ({ $organic_pct }%)
 
-stats-top-inviters-btn = 🏆 Top inviters
+stats_top_inviters_btn = 🏆 Top inviters
 
-stats-top-inviters-header = 🏆 Top { $limit } inviters:
+stats_top_inviters_header = 🏆 Top { $limit } inviters:
 
-stats-no-inviters = No inviters yet
+stats_no_inviters = No inviters yet
 
-referral-info =
+referral_info =
     🔗 Your referral link:
     { $link }
 
     👥 Invited users: { $count }
 
-referral-user-not-found = User not found. Please use /start first.
+referral_user_not_found = User not found. Please use /start first.
diff --git a/locales/ru/admin.ftl b/locales/ru/admin.ftl
@@ -1,3 +1,3 @@
 # Сообщения для администраторов
-example-executed = Пример админской команды выполнен
-bot-started = Бот запущен!
+example_executed = Пример админской команды выполнен
+bot_started = Бот запущен!
diff --git a/locales/ru/common.ftl b/locales/ru/common.ftl
@@ -1,2 +1,2 @@
 # Общие строки
-echo-unknown-message = Я не понимаю это сообщение. Используйте /start чтобы начать.
+echo_unknown_message = Я не понимаю это сообщение. Используйте /start чтобы начать.
diff --git a/locales/ru/settings.ftl b/locales/ru/settings.ftl
@@ -1,18 +1,18 @@
 # Сообщения настроек
-settings-title = ⚙️ Настройки
+settings_title = ⚙️ Настройки
 
     Выберите опцию:
-settings-language-title = 🌐 Язык
+settings_language_title = 🌐 Язык
 
     Выберите язык:
-settings-language-changed = ✅ Язык успешно изменён.
+settings_language_changed = ✅ Язык успешно изменён.
 
 # Онбординг
-onboarding-language = 🌐 Пожалуйста, выберите язык:
+onboarding_language = 🌐 Пожалуйста, выберите язык:
 
 # Кнопки
-btn-language = 🌐 Язык
-btn-settings = ⚙️ Настройки
-btn-back = ↩️ Назад
-lang-en = 🇬🇧 English
-lang-ru = 🇷🇺 Русский
+btn_language = 🌐 Язык
+btn_settings = ⚙️ Настройки
+btn_back = ↩️ Назад
+lang_en = 🇬🇧 English
+lang_ru = 🇷🇺 Русский
diff --git a/locales/ru/stats.ftl b/locales/ru/stats.ftl
@@ -1,20 +1,20 @@
-stats-overview =
+stats_overview =
     📊 Статистика
 
     Всего пользователей: { $total }
     По рефералам: { $referred } ({ $referred_pct }%)
     Органика: { $organic } ({ $organic_pct }%)
 
-stats-top-inviters-btn = 🏆 Топ инвайтеров
+stats_top_inviters_btn = 🏆 Топ инвайтеров
 
-stats-top-inviters-header = 🏆 Топ-{ $limit } инвайтеров:
+stats_top_inviters_header = 🏆 Топ-{ $limit } инвайтеров:
 
-stats-no-inviters = Пока нет инвайтеров
+stats_no_inviters = Пока нет инвайтеров
 
-referral-info =
+referral_info =
     🔗 Ваша реферальная ссылка:
     { $link }
 
     👥 Приглашённых пользователей: { $count }
 
-referral-user-not-found = Пользователь не найден. Сначала используйте /start.
+referral_user_not_found = Пользователь не найден. Сначала используйте /start.
diff --git a/scripts/generate_i18n_stubs.py b/scripts/generate_i18n_stubs.py
@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""Generate Python type stubs for fluentogram translations.
+"""Generate Python types file for fluentogram translations.
 
-This script parses .ftl files and generates a .pyi stub file
-that provides IDE autocomplete for translation keys.
+This script parses .ftl files and generates a types.py file
+that provides IDE autocomplete for translation keys with runtime
+compatibility via TYPE_CHECKING guard.
 """
 
 import re
@@ -65,39 +66,53 @@ def extract_ftl_keys(ftl_content: str) -> list[tuple[str, list[str]]]:
     return keys
 
 
-def generate_stub_content(all_keys: dict[str, list[str]]) -> str:
-    """Generate .pyi stub content for FluentTranslator."""
+def generate_types_content(all_keys: dict[str, list[str]]) -> str:
+    """Generate types.py content with TYPE_CHECKING guard for FluentTranslator."""
     lines = [
-        '"""Auto-generated type stubs for fluentogram translations.',
+        '"""Auto-generated types file for fluentogram translations.',
         "",
         "Generated by scripts/generate_i18n_stubs.py",
-        "Do not edit manually - regenerate with: python scripts/generate_i18n_stubs.py",
+        "Do not edit manually - regenerate with: uv run python scripts/generate_i18n_stubs.py",
         '"""',
         "",
+        "from typing import TYPE_CHECKING, TypeVar",
         "",
-        "class TranslatorRunner:",
-        '    """Type stubs for FluentTranslator with all available translation keys."""',
+        "if TYPE_CHECKING:",
+        '    _I18nArg = TypeVar("_I18nArg", str, int)',
+        "",
+        "    class TranslatorRunner:",
+        '        """Type stubs for FluentTranslator with all available translation keys."""',
+        "",
+        "        def get(self, key: str, **kwargs: _I18nArg) -> str: ...",
         "",
     ]
 
     for key, params in sorted(all_keys.items()):
         # Convert kebab-case to snake_case for method name
         method_name = key.replace("-", "_")
         if params:
-            param_str = ", ".join(f"{p}: str | int" for p in params)
-            lines.append(f"    def {method_name}(self, *, {param_str}) -> str: ...")
+            param_str = ", ".join(f"{p}: _I18nArg" for p in params)
+            lines.append(f"        def {method_name}(self, *, {param_str}) -> str: ...")
         else:
-            lines.append(f"    def {method_name}(self) -> str: ...")
+            lines.append(f"        def {method_name}(self) -> str: ...")
+
+    lines.extend(
+        [
+            "",
+            "else:",
+            "    from fluentogram import TranslatorRunner  # noqa: F401",
+            "",
+        ]
+    )
 
-    lines.append("")
     return "\n".join(lines)
 
 
 def main() -> None:
-    """Generate stubs from locale files."""
+    """Generate types file from locale files."""
     project_root = Path(__file__).parent.parent
     locales_dir = project_root / "locales"
-    output_file = project_root / "src" / "infrastructure" / "i18n" / "stubs.pyi"
+    output_file = project_root / "src" / "infrastructure" / "i18n" / "types.py"
 
     # Use English as the reference locale
     en_dir = locales_dir / "en"
@@ -110,7 +125,7 @@ def main() -> None:
 
     # Parse all .ftl files in the English locale
     for ftl_file in en_dir.glob("*.ftl"):
-        content = ftl_file.read_text()
+        content = ftl_file.read_text(encoding="utf-8")
         keys = extract_ftl_keys(content)
         for key, params in keys:
             all_keys[key] = params
@@ -120,12 +135,12 @@ def main() -> None:
         print("Error: No translation keys found")
         return
 
-    # Generate stub content
-    stub_content = generate_stub_content(all_keys)
+    # Generate types content
+    types_content = generate_types_content(all_keys)
 
-    # Write stub file
+    # Write types file
     output_file.parent.mkdir(parents=True, exist_ok=True)
-    output_file.write_text(stub_content)
+    output_file.write_text(types_content)
     print(f"\nGenerated {output_file} with {len(all_keys)} translation methods")
 
 
diff --git a/src/infrastructure/i18n/__init__.py b/src/infrastructure/i18n/__init__.py
@@ -6,10 +6,12 @@
     create_translator_hub,
 )
 from .provider import I18nProvider
+from .types import TranslatorRunner
 
 __all__ = [
     "DEFAULT_LANGUAGE",
     "SUPPORTED_LANGUAGES",
     "I18nProvider",
+    "TranslatorRunner",
     "create_translator_hub",
 ]
diff --git a/src/infrastructure/i18n/hub.py b/src/infrastructure/i18n/hub.py
@@ -48,4 +48,4 @@ def create_translator_hub(locale_dir: Path | None = None) -> TranslatorHub:
         "ru": ("ru", "en"),
     }
 
-    return TranslatorHub(locale_map, translators, root_locale="en")
+    return TranslatorHub(locale_map, translators, root_locale="en", separator="_")
diff --git a/src/infrastructure/i18n/stubs.pyi b/src/infrastructure/i18n/stubs.pyi
diff --git a/src/infrastructure/i18n/types.py b/src/infrastructure/i18n/types.py
@@ -0,0 +1,46 @@
+"""Auto-generated types file for fluentogram translations.
+
+Generated by scripts/generate_i18n_stubs.py
+Do not edit manually - regenerate with: uv run python scripts/generate_i18n_stubs.py
+"""
+
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    _I18nArg = TypeVar("_I18nArg", str, int)
+
+    class TranslatorRunner:
+        """Type stubs for FluentTranslator with all available translation keys."""
+
+        def get(self, key: str, **kwargs: _I18nArg) -> str: ...
+
+        def bot_started(self) -> str: ...
+        def btn_back(self) -> str: ...
+        def btn_language(self) -> str: ...
+        def btn_settings(self) -> str: ...
+        def echo_unknown_message(self) -> str: ...
+        def example_executed(self) -> str: ...
+        def lang_en(self) -> str: ...
+        def lang_ru(self) -> str: ...
+        def onboarding_language(self) -> str: ...
+        def referral_info(self, *, link: _I18nArg, count: _I18nArg) -> str: ...
+        def referral_user_not_found(self) -> str: ...
+        def settings_language_changed(self) -> str: ...
+        def settings_language_title(self) -> str: ...
+        def settings_title(self) -> str: ...
+        def stats_no_inviters(self) -> str: ...
+        def stats_overview(
+            self,
+            *,
+            total: _I18nArg,
+            referred: _I18nArg,
+            referred_pct: _I18nArg,
+            organic: _I18nArg,
+            organic_pct: _I18nArg,
+        ) -> str: ...
+        def stats_top_inviters_btn(self) -> str: ...
+        def stats_top_inviters_header(self, *, limit: _I18nArg) -> str: ...
+        def welcome(self, *, name: _I18nArg) -> str: ...
+
+else:
+    from fluentogram import TranslatorRunner  # noqa: F401
diff --git a/src/presentation/bot/main.py b/src/presentation/bot/main.py
@@ -29,7 +29,7 @@ async def notify_admins_on_startup(
     i18n = hub.get_translator_by_locale(DEFAULT_LANGUAGE)
     for admin_id in config.telegram.admin_ids:
         try:
-            await bot.send_message(chat_id=admin_id, text=i18n.get("bot-started"))
+            await bot.send_message(chat_id=admin_id, text=i18n.get("bot_started"))
         except TelegramAPIError as e:
             logging.warning("Failed to notify admin %s: %s", admin_id, e)
 
diff --git a/src/presentation/bot/routers/admin/stats.py b/src/presentation/bot/routers/admin/stats.py
@@ -32,7 +32,7 @@ async def stats_handler(
         inline_keyboard=[
             [
                 InlineKeyboardButton(
-                    text=i18n.get("stats-top-inviters-btn"),
+                    text=i18n.get("stats_top_inviters_btn"),
                     callback_data="ref_top",
                 ),
                 InlineKeyboardButton(
@@ -45,7 +45,7 @@ async def stats_handler(
 
     await message.answer(
         text=i18n.get(
-            "stats-overview",
+            "stats_overview",
             total=stats.total_users,
             referred=stats.referred_count,
             referred_pct=stats.referred_percent,
@@ -71,11 +71,11 @@ async def ref_top_callback(
     top = await interactor(limit)
 
     if not top:
-        await callback.message.edit_text(text=i18n.get("stats-no-inviters"))
+        await callback.message.edit_text(text=i18n.get("stats_no_inviters"))
         await callback.answer()
         return
 
-    text = i18n.get("stats-top-inviters-header", limit=limit) + "\n\n"
+    text = i18n.get("stats_top_inviters_header", limit=limit) + "\n\n"
     for i, ref in enumerate(top, 1):
         name = f"@{ref.username}" if ref.username else ref.first_name
         text += f"{i}. {name} — {ref.count}\n"
@@ -101,7 +101,7 @@ async def cb_back_to_stats(
         inline_keyboard=[
             [
                 InlineKeyboardButton(
-                    text=i18n.get("stats-top-inviters-btn"),
+                    text=i18n.get("stats_top_inviters_btn"),
                     callback_data="ref_top",
                 ),
                 InlineKeyboardButton(
@@ -114,7 +114,7 @@ async def cb_back_to_stats(
 
     await callback.message.edit_text(
         text=i18n.get(
-            "stats-overview",
+            "stats_overview",
             total=stats.total_users,
             referred=stats.referred_count,
             referred_pct=stats.referred_percent,
diff --git a/src/presentation/bot/routers/commands.py b/src/presentation/bot/routers/commands.py
diff --git a/src/presentation/bot/routers/echo.py b/src/presentation/bot/routers/echo.py
diff --git a/src/presentation/bot/routers/onboarding.py b/src/presentation/bot/routers/onboarding.py
diff --git a/src/presentation/bot/routers/referral.py b/src/presentation/bot/routers/referral.py
diff --git a/src/presentation/bot/routers/settings.py b/src/presentation/bot/routers/settings.py
diff --git a/src/presentation/bot/utils/markups/settings.py b/src/presentation/bot/utils/markups/settings.py

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`# Common strings shared across features`
`2`		`-echo-unknown-message = I don't understand this message. Use /start to begin.`
	`2`	`+echo_unknown_message = I don't understand this message. Use /start to begin.`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`# Общие строки`
`2`		`-echo-unknown-message = Я не понимаю это сообщение. Используйте /start чтобы начать.`
	`2`	`+echo_unknown_message = Я не понимаю это сообщение. Используйте /start чтобы начать.`