---
title: 'Frontend Internationalization (i18n) Support'
slug: 'frontend-i18n-support'
created: '2026-03-08'
status: 'in-progress'
stepsCompleted: [1]
tech_stack: [react-i18next, i18next, i18next-browser-languagedetector]
files_to_modify: []
code_patterns: []
test_patterns: []
---

# Tech-Spec: Frontend Internationalization (i18n) Support

**Created:** 2026-03-08

## Overview

### Problem Statement

The ecommerce frontend currently only supports Japanese (日本語) with text hardcoded in a centralized `labels.ts` file (~50+ strings) and ~10-15 additional hardcoded strings scattered across 12 component files. This limits the application's usability to Japanese-speaking users and prevents expansion to other markets.

### Solution

Integrate `react-i18next` to replace the current `LABELS` constant system with a proper internationalization framework. Create translation JSON files for Japanese (ja) and English (en), add a language switcher dropdown in the Header component, implement locale-aware date/number formatting, and persist the user's language preference in localStorage. The architecture will be designed for easy addition of new languages.

### Scope

**In Scope:**
- Install and configure `react-i18next`, `i18next`, and `i18next-browser-languagedetector`
- Migrate ~50+ strings from `labels.ts` to translation JSON files (ja, en)
- Move ~10-15 hardcoded Japanese strings into the translation system
- Add language switcher dropdown in `Header.tsx`
- Implement locale-aware `Intl.NumberFormat` / `Intl.DateTimeFormat` in `format.ts`
- Persist selected language to `localStorage`
- Extensible structure for adding new languages easily

**Out of Scope:**
- Backend translation / API response localization
- Adding a 3rd+ language (only ja + en initially)
- RTL (right-to-left) support
- SEO / URL-based locale routing

## Context for Development

### Codebase Patterns

- React 19 + TypeScript + Vite + Tailwind CSS
- All UI labels currently centralized in `src/constants/labels.ts` as a single `LABELS` object exported with `as const`
- Components import and reference labels via `LABELS.propertyName`
- Date/number formatting hardcoded to `ja-JP` locale in `src/utils/format.ts`
- Layout uses `AppLayout` → `Header` + `Sidebar` pattern
- 6 pages, 15 components, 4 hooks, 4 API modules

### Files to Reference

| File | Purpose |
| ---- | ------- |
| `src/constants/labels.ts` | Centralized Japanese UI labels (~50+ strings) — primary migration target |
| `src/utils/format.ts` | Date/number formatting with hardcoded `ja-JP` locale |
| `src/components/layout/Header.tsx` | Header component — language switcher will be added here |
| `src/components/layout/Sidebar.tsx` | Contains hardcoded "管理画面" text |
| `src/components/layout/AppLayout.tsx` | Main layout wrapper |
| `src/pages/DashboardPage.tsx` | Hardcoded subtitle and table headers |
| `src/pages/OrdersPage.tsx` | Hardcoded subtitle and button text |
| `src/pages/NotificationsPage.tsx` | Hardcoded subtitle and table headers |
| `src/pages/PaymentsPage.tsx` | Hardcoded subtitle |
| `src/pages/SystemStatusPage.tsx` | Hardcoded subtitle and table header |
| `src/components/orders/OrderForm.tsx` | Hardcoded Japanese placeholders |
| `src/components/orders/OrderDetail.tsx` | Hardcoded "小計" text |
| `src/components/orders/OrderList.tsx` | Hardcoded "ステータス" text |
| `src/components/orders/BulkImportBanner.tsx` | Hardcoded tooltip text |
| `src/components/dashboard/OrdersChart.tsx` | Hardcoded chart label |
| `src/components/dashboard/RevenueChart.tsx` | Hardcoded chart name |
| `index.html` | Hardcoded Japanese page title |

### Technical Decisions

- **i18n Library:** `react-i18next` — industry standard, large ecosystem, supports namespaces, lazy loading, and pluralization
- **Translation file format:** JSON — simple, widely supported, easy to hand off to translators
- **Language persistence:** `localStorage` via `i18next-browser-languagedetector`
- **Language switcher placement:** Dropdown in `Header.tsx` (right side)
- **Locale formatting:** Dynamic `Intl.NumberFormat` / `Intl.DateTimeFormat` based on selected language
- **Architecture:** Extensible — new languages added by creating a new JSON translation file and registering it

## Implementation Plan

### Tasks

{tasks}

### Acceptance Criteria

{acceptance_criteria}

## Additional Context

### Dependencies

{dependencies}

### Testing Strategy

{testing_strategy}

### Notes

{notes}