feat(i18n): Phase 1 - Extract strings + i18next foundation

[hoteye]

Phase 1: Extract strings + i18next foundation

Resolves #6525
Following cornmander's phased approach feedback in #6832, this PR implements Phase 1 with the exact scope and goals outlined.

Phase 1 Requirements Implementation

Set up i18next infrastructure:

• Real i18next + react-i18next integration
• English-only locale configuration
• Proper fallback mechanisms

Extract UI strings using t() function:

• Help component: All sections, shortcuts, and descriptions
• AuthDialog: Authentication options, instructions, error messages
• SettingsDialog: Title, instructions, restart prompts

Introduce only en locale (no user-facing changes):

• All translation values identical to main branch strings
• Zero behavioral changes - pure refactoring
• Preserved styling (AccentPurple highlights, formatting)

Focus on core components:

• Help, Auth, Settings dialogs
• Scope limited to these 3 components for reviewability

File Structure (as approved)

src/i18n/
├── index.ts              # i18next configuration
├── locales/en/
│   ├── common.json       # Common UI strings  
│   ├── help.json         # Help component strings
│   └── dialogs.json      # Dialog strings
└── useTranslation.ts     # React hook wrapper

Testing (Phase 1 inclusion)

• src/i18n/index.test.ts - Basic i18n functionality tests
• Verifies t() function works correctly
• Tests fallback behavior for missing keys
• Ensures infrastructure is solid for Phase 2

Changes Summary

• 12 files changed, 334 insertions, 54 deletions
• New dependencies: i18next ^25.4.1, react-i18next ^15.3.2
• No breaking changes - all existing functionality preserved
• Build and tests pass - ready for review

Verification

• String consistency confirmed against main branch
• Rendering effects preserved (colors, formatting)
• Zero user-facing changes
• Infrastructure ready for Phase 2 locale picker

Next: Phase 2

Once this foundation is approved, Phase 2 will add the Language option to SettingsDialog with locale switching logic (still English-only), preparing for Phase 3 incremental locale additions.

Addresses: #6525
Follows: cornmander's phased approach in #6832

[gemini-code-assist]

Summary of Changes

Hello @hoteye, 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 establishes the foundational internationalization (i18n) framework for the application. It integrates the i18next library and extracts existing English UI strings from key components into dedicated locale files. The primary goal is to set up the necessary infrastructure for future language support without introducing any immediate user-visible changes or altering current functionality.

Highlights

• i18next Infrastructure Setup: Integrated i18next and react-i18next, configuring it for English-only locale with proper fallback mechanisms. This lays the groundwork for future internationalization efforts.
• String Extraction: Extracted all UI strings from the Help component, AuthDialog, and SettingsDialog using the new t() function, centralizing them into dedicated JSON locale files.
• New Dependencies: Added i18next (^25.4.1) and react-i18next (^15.3.2) as new project dependencies.
• No User-Facing Changes: Ensured that all translation values are identical to existing strings, resulting in zero behavioral or user-facing changes in this phase. Styling (e.g., AccentPurple highlights) is preserved.
• Targeted Scope: Focused the initial string extraction and i18next integration solely on the Help, Auth, and Settings dialogs to maintain reviewability and manage complexity for this foundational phase.
• Testing Included: Introduced a new test file (src/i18n/index.test.ts) to verify basic i18n functionality, including the t() function and fallback behavior, ensuring the infrastructure is solid for subsequent phases.

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 in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

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 issue 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 introduces a solid foundation for internationalization using i18next and react-i18next. The approach of extracting strings from core components (Help, AuthDialog, SettingsDialog) into a new src/i18n structure is well-executed and follows the phased plan outlined. My review focuses on improving the robustness and performance of the new i18n initialization logic. I've identified a critical issue with error handling and a high-severity performance concern with synchronous file loading. Addressing these will ensure the new infrastructure is scalable and resilient for future phases.

[hoteye]

Hi @cornmander Phase 1 implementation ready for review, following your guidance from #6832.
Thank you for the clear direction!

[cornmander]

Please fix linting errors.

[cornmander]

Could you also add an internationalization.md file under https://github.com/google-gemini/gemini-cli/tree/main/docs/cli describing how developers should add and reference new strings, and how they run the coverage report?

[gemini-code-assist]

Thank you for the suggestion, @cornmander! I cannot directly add files to the repository. However, @hoteye, you can create the internationalization.md file under docs/cli as requested. This document should cover:

• How developers should add and reference new strings.
• How to run the internationalization coverage report.

This will be a valuable addition for future development. Please let me know if you'd like me to review a draft of this document once it's created.

[cornmander]

Thanks! I think this is great. Just left one comment for you.

[hoteye]

Hi @cornmander,

Regarding your concerns about i18n affecting yargs locale in PR #8242:

Current Phase 1 Status (Safe)

• English-only: languages = ['en'] in our i18n config
• No system locale detection: Hardcoded to English, tests remain stable
• No impact on yargs: Our i18n doesn't interfere with yargs error messages

Future Multi-language Solution

When we add multi-language support in Phase 2+:

1. Test Environment Isolation

// test-setup.ts
process.env.LC_ALL = 'C';
process.env.LANG = 'en_US.UTF-8';

2. Conditional Language Loading

// Force English in tests, user preference in production
lng: process.env.VITEST ? 'en' : getUserLanguage()

3. Improved Testing Strategy

• Assert translation keys instead of literal strings
• Mock translation functions to isolate i18n from business logic tests

TL;DR: Phase 1 won't cause the yargs localization issues. We have a clear plan for handling this when we add multi-language support later.

Thanks for flagging this early - it helps us build more robust software!

[hoteye]

Hi @cornmander ,

PR is ready for review. I've successfully run all tests locally after merging with upstream/main:

• All 4,322 tests passing
• ESLint and Prettier checks pass
• Error detection for renderStyledText implemented as requested

Since this is from a fork, CI needs manual triggering. Happy to provide any additional information you need.

Thanks!

[jacob314]

The new approach looks reasonable if a bit cumbersome and opaque compared to the original syntax. However I can't think of something better. I'm open to going with this syntax but we will need to provide careful GEMINI.md instructions to make sure Gemini CLI can use the new syntax well when generating code.

[hoteye]

Hi @jacob314,

Update: I've fixed the missing translation files issue that was causing test failures. Updated scripts/copy_bundle_assets.js to automatically copy i18n locale files to the bundle directory during build.

However, there's still a CI artifact naming conflict affecting macOS jobs:

Failed to CreateArtifact: Received non-retryable error: Failed request: (409) Conflict: 
an artifact with this name already exists on the workflow run

This appears to be a CI infrastructure issue that needs to be resolved by the team.

My Phase 1 i18n implementation is ready for review. All tests pass locally and the translation infrastructure is working correctly.

Thanks!

[hoteye]

/gemini review

[gemini-code-assist]

Code Review

This pull request lays a solid foundation for internationalization by introducing i18next and extracting strings from core UI components. The addition of comprehensive documentation and a utility for handling styled text (renderStyledText) is excellent.

My review focuses on two main points to further strengthen this foundation. First, ensuring the application fails fast if translation files are missing, which is critical for startup integrity. Second, refactoring a case of string concatenation to adhere to the "Semantic Complete" principle, which will improve maintainability and translator experience.

Overall, this is a well-executed first phase for a significant feature.

[gemini-code-assist]

Code Review

This pull request introduces a solid foundation for internationalization using i18next and react-i18next. The extraction of strings from core components like Help, AuthDialog, and SettingsDialog is well-executed. The introduction of the renderStyledText utility is a clever solution for handling styled text within the terminal environment, and the accompanying documentation is thorough and helpful for future contributors. The overall structure is clean and scalable.

My main concern, which I've flagged as critical, is the use of top-level await for i18n initialization. This will block module loading and negatively impact startup performance as more locales are added. I've suggested an alternative approach to handle initialization asynchronously without blocking.

[hoteye]

/gemini review

[gemini-code-assist]

Code Review

This pull request lays a solid foundation for internationalization in the Gemini CLI. The extraction of strings into separate locale files and the introduction of the useTranslation hook are well-executed. The renderStyledText utility is a particularly clever solution for handling styled text within the constraints of a terminal UI. I've identified two critical issues related to path resolution in development and the test setup that need to be addressed to ensure the feature works correctly for all developers and that tests can run reliably. Once these are fixed, this will be an excellent addition to the codebase.

[hoteye]

@jacob314 Hi! Phase 1 implementation is complete and ready for review. All changes committed with improved settings dialog UX and code formatting. Thanks for prioritizing the review as promised!

[hoteye]

@jacob314 Could you please take another look at this PR? All checks have passed, thanks!