browser/.kiro/specs/angular-localize-migration/requirements.md

Requirements Document

Introduction

This feature involves migrating the Bitwarden client applications from the current custom i18n system (I18nService and I18nPipe) to Angular's built-in localization system (@angular/localize). This migration will standardize the internationalization approach, improve build-time optimization, and leverage Angular's mature localization tooling.

Requirements

Requirement 1

User Story: As a developer, I want to use Angular's standard localization system, so that the codebase follows Angular best practices and benefits from framework optimizations.

Acceptance Criteria

1. WHEN the migration is complete THEN the system SHALL use @angular/localize instead of the custom I18nService
2. WHEN building the application THEN Angular's localization build process SHALL extract and process translation strings at build time
3. WHEN the application runs THEN all existing translation functionality SHALL work identically to the current system
4. WHEN developers add new translatable strings THEN they SHALL use Angular's i18n markers instead of the custom i18n pipe

Requirement 2

User Story: As a user, I want the application to continue supporting all current languages and locales, so that my experience remains unchanged after the migration.

Acceptance Criteria

1. WHEN the migration is complete THEN all existing translation files SHALL be converted to Angular's XLIFF format
2. WHEN switching languages THEN the application SHALL maintain the same language switching behavior
3. WHEN using locale-specific formatting THEN numbers, dates, and currencies SHALL display correctly for each supported locale
4. WHEN the application loads THEN the user's previously selected language preference SHALL be preserved

Requirement 3

User Story: As a developer, I want template translations to use Angular's i18n attributes, so that translations are extracted and optimized at build time.

Acceptance Criteria

1. WHEN templates contain translatable text THEN they SHALL use i18n attributes instead of the i18n pipe
2. WHEN templates have dynamic content THEN they SHALL use Angular's ICU expressions for pluralization and interpolation
3. WHEN building the application THEN Angular's extraction tool SHALL automatically identify all translatable strings
4. WHEN templates are processed THEN the i18n pipe SHALL be completely removed from all template files

Requirement 4

User Story: As a developer, I want TypeScript code translations to use Angular's localize function, so that runtime translations work seamlessly with the new system.

Acceptance Criteria

1. WHEN TypeScript code needs translations THEN it SHALL use the $localize function instead of I18nService.t()
2. WHEN the application runs THEN all programmatic translations SHALL work identically to the current system
3. WHEN building the application THEN the $localize calls SHALL be processed and optimized by Angular's build system
4. WHEN code uses translation parameters THEN they SHALL be properly handled by the $localize function

Requirement 5

User Story: As a developer, I want the build system to support multiple locales, so that we can generate locale-specific builds efficiently.

Acceptance Criteria

1. WHEN building the application THEN the build system SHALL support generating separate bundles for each locale
2. WHEN configuring builds THEN developers SHALL be able to specify which locales to build
3. WHEN the build completes THEN each locale SHALL have its own optimized bundle with embedded translations
4. WHEN serving the application THEN the correct locale bundle SHALL be served based on user preferences

Requirement 6

User Story: As a developer, I want comprehensive tooling support, so that I can efficiently manage translations throughout the development lifecycle.

Acceptance Criteria

1. WHEN extracting translations THEN the Angular CLI SHALL automatically generate XLIFF files from source code
2. WHEN updating translations THEN the system SHALL support merging new strings with existing translation files
3. WHEN building for production THEN unused translation strings SHALL be tree-shaken from the final bundles
4. WHEN developing locally THEN the system SHALL support hot-reloading with translation changes

Requirement 7

User Story: As a developer, I want backward compatibility during the migration, so that the transition can be done incrementally without breaking the application.

Acceptance Criteria

1. WHEN migrating components THEN both old and new i18n systems SHALL coexist temporarily
2. WHEN the migration is in progress THEN the application SHALL continue to function normally
3. WHEN components are migrated THEN they SHALL be tested to ensure identical functionality
4. WHEN the migration is complete THEN all legacy i18n code SHALL be removed from the codebase