Locale Detection¶

KanjiIQ automatically detects the user's region and presents a curated subset of languages relevant to their locale. This avoids overwhelming users with a 51-language dropdown while still making all languages accessible.

Detection Chain¶

graph TD
    A[New User Visit] --> B[Read device locale<br/>Platform.localeName]
    B --> C[Extract locale code<br/>e.g., pt-BR, en-US, ja-JP]
    C --> D{Cached config<br/>available?}
    D -->|Yes, < 7 days| E[Use cached config]
    D -->|No| F[API call:<br/>GET /api/v1/config/locale/:locale]
    F --> G{Locale<br/>recognized?}
    G -->|Yes| H[Return locale config<br/>7-17 languages]
    G -->|No| I[Return default config<br/>12 major languages]
    H --> J[Cache in SharedPreferences<br/>TTL: 7 days]
    I --> J
    J --> K[Display language selector]

Priority Order¶

The locale detector resolves the user's locale through:

Account locale — If the user has a saved preference
Device locale — Platform.localeName (e.g., pt_BR)
Browser language — navigator.language (web only)
Fallback — English (en)

Pre-Configured Locales¶

The locale_configs database table stores 30 pre-configured locale mappings:

Locale	Default Languages	Total Available
`pt-BR`	Portuguese, English, Spanish	7
`ja-JP`	Japanese, English, Chinese (Simplified), Korean	17
`en-US`	English, Spanish, French	12
`fr-FR`	French, English, Spanish, German	10
`de-DE`	German, English, French, Dutch	10
`ar-SA`	Arabic, English, French	8
`hi-IN`	Hindi, English, Bengali, Tamil, Telugu, Punjabi	12
...	...	...

Each locale defines:

Default languages: Shown initially (3-5 most relevant)
Available languages: Full regional set (7-17 languages)

"Show All Languages" Toggle¶

Users can always override locale detection:

A toggle labeled "Show all 51 languages" expands the language selector to the full list
This preference is persisted in SharedPreferences
Once enabled, it overrides locale-based filtering for that device

API Endpoint¶

GET /api/v1/config/locale/:locale

Response:

{
  "locale": "pt-BR",
  "defaultLanguages": ["pt", "en", "es"],
  "availableLanguages": ["pt", "en", "es", "fr", "it", "de", "ca"],
  "showAllOption": true
}

Admin Management¶

Locale configurations are managed through the admin dashboard:

Add new locales as user demand emerges
Adjust language lists based on regional analytics
View regional traffic to identify underserved locales

See the admin API at POST /api/v1/admin/locales for configuration management.