#8060: i18n (1/4) - core infrastructure

[jethac]

Summary

This is the first of four pull requests to implement the i18n system for Gemini CLI. This initial PR establishes the core infrastructure, utility patterns, and CLI entrypoint integration, using @hoteye's original work from PR #8060 as the foundation.

Implements Phase 1 of Issue #6525 (i18n infrastructure + core string extraction).
Supersedes PR #17738 (Previous 100+ commit PR being split into manageable semantic chunks).
Supersedes part of PR #8060 (hoteye's foundation, preserved with original authorship).

What's Included

From @hoteye's original work (preserved with authorship):

• i18next + react-i18next: Core infrastructure and configuration.
• renderStyledText utility: A novel solution for semantic interpolation in Ink terminal environments, allowing React components to be used within translations without fragmenting keys.
• Core English Locale Skeleton: Establishes namespaces (common.json, help.json, dialogs.json) and foundational UI strings.

New in this PR:

• CLI Entrypoint Integration: i18n is initialized at startup in gemini.tsx so translations are available before the UI renders.
• Test Environment Foundation: i18n is initialized in test-setup.ts, ensuring unit tests use the translation system correctly.
• Dynamic Language Detection: Logic to automatically detect preferred language via GEMINI_LANG, LANG, or the Intl API.
• Enhanced Error Handling: Robust error handling for translation loading (specifically handled ENOENT vs malformed files) as requested by gemini-code-assist.
• Pre-commit & Build Integration: Scripts updated to ensure locale files are bundled and linted.

PR Stack

Pull Request	Scope	Status
PR #18171 (This)	Core Infrastructure & Foundation	🚀 Ready
PR #18182	Settings Integration & Asset Discovery	📋 Future
PR #18184	User Locales (~/.gemini/locales)	📋 Future
pending	UI Component Migrations & Japanese Locale	📋 Future

Architecture Highlights

Semantic Interpolation for Ink

Terminal UIs often require complex styling (bolding, colors) mid-sentence. Instead of breaking translations into fragments (which destroys context for translators), this PR introduces renderStyledText:

// Translation: "Welcome {name}! Use {cmd} to start."
renderStyledText(t('welcome'), {
  name: <Text bold color="green">User</Text>,
  cmd: <Text color="purple">/start</Text>
})

Testing

cd packages/cli
npm run build
npm test src/i18n/index.test.ts src/ui/utils/styledText.test.tsx

Attribution

The i18next infrastructure and renderStyledText utility is entirely @hoteye's work from PR #8060. This PR preserves hoteye's original commit to maintain attribution.

[gemini-code-assist]

Summary of Changes

Hello @jethac, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request lays the essential groundwork for internationalization (i18n) within the CLI application. It integrates the i18next library, sets up a robust system for dynamic language detection and translation resource loading, and introduces a novel renderStyledText utility. This utility is crucial for maintaining semantic context in translations while allowing for rich, styled output in the Ink-based UI. This initial phase establishes the core capabilities needed to support multiple languages across the application.

Highlights

• Core i18n Infrastructure: The foundational i18next and react-i18next libraries have been integrated, establishing the core internationalization framework for the CLI application.
• Dynamic Language Detection and Resource Loading: The system now includes logic to automatically detect the user's preferred language from environment variables or the Intl API, and dynamically loads corresponding translation files, with English as a fallback.
• Semantic Interpolation for Styled Text: A new renderStyledText utility has been introduced. This function allows for rich, styled text within translations by enabling React components to be used as interpolations, ensuring translators maintain full semantic context while providing flexible UI styling.
• Translation File Structure and Initial Locales: A clear directory structure (packages/cli/src/i18n/locales/<lang>/<namespace>.json) has been set up, along with initial English translation files for common UI elements, dialogs, and help content.
• Build and Test Integration: The build script has been updated to ensure locale files are copied into the final bundle, and comprehensive unit tests have been added for both the i18n foundation and the renderStyledText utility, including strict validation for placeholder usage.

Changelog

• docs/CONTRIBUTING.md
  • Fixed a newline character.
• package-lock.json
  • Updated @babel/runtime to 7.28.6.
  • Added new dependencies: html-parse-stringify@3.0.1, i18next@25.8.0, react-i18next@15.7.4, and void-elements@3.1.0.
• packages/cli/package.json
  • Added i18next (^25.4.1) and react-i18next (^15.3.2) as dependencies.
• packages/cli/src/gemini.tsx
  • Added an import to initialize the i18n system at the CLI entrypoint, ensuring translations are ready before React components render.
• packages/cli/src/i18n/index.test.ts
  • Added a new test file with comprehensive unit tests for the i18n foundation, covering basic translation functionality, fallback mechanisms, default namespaces, and translation completeness for various UI elements.
• packages/cli/src/i18n/index.ts
  • Added the core i18n setup file, including dynamic resource loading, synchronous detection of available languages, system language detection (via environment variables or Intl API), and i18next initialization.
• packages/cli/src/i18n/locales/en/common.json
  • Added English translations for common UI elements like buttons, loading states, and status messages.
• packages/cli/src/i18n/locales/en/dialogs.json
  • Added English translations for various dialogs, including authentication and settings.
• packages/cli/src/i18n/locales/en/help.json
  • Added English translations for help sections, covering basics, commands, and keyboard shortcuts.
• packages/cli/src/ui/utils/styledText.test.tsx
  • Added a new test file for the renderStyledText utility, including tests for rendering styled interpolations, correct styling attributes, and robust error handling for placeholder mismatches.
• packages/cli/src/ui/utils/styledText.tsx
  • Added a new utility function renderStyledText to render text with styled React components as interpolations, implementing the 'Semantic Interpolation Pattern' and including strict validation for placeholder usage.
• packages/cli/test-setup.ts
  • Modified to ensure the i18n system is initialized before all tests run.
• scripts/copy_bundle_assets.js
  • Updated the build script to copy i18n locale files from packages/cli/src/i18n/locales to bundle/locales, ensuring they are included in the final application bundle.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request establishes a solid foundation for internationalization using i18next. The changes are well-structured, including the core i18n setup, initial English translation files, and a clever utility for rendering styled text. The accompanying tests are comprehensive. My review focuses on enhancing the robustness of error handling in the new i18n module to prevent silent failures and make debugging easier, aligning with our repository's guidelines on detailed error logging. I've identified a couple of areas where improvements can be made.

[jethac]

@jacob314 as discussed, this is part 1 of the work that was on #17738

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI. We really appreciate the time and effort you've put into this pull request.

To keep our backlog manageable and ensure we're focusing on current priorities, we are closing pull requests that haven't seen maintainer activity for 30 days. Currently, the team is prioritizing work associated with 🔒 maintainer only or help wanted issues.

If you believe this change is still critical, please feel free to comment with updated details. Otherwise, we encourage contributors to focus on open issues labeled as help wanted. Thank you for your understanding!