Skip to content

Commit d6fa1e3

Browse files
busypeoplesbusypeoples
authored
Merge pull request #18 from lingualdev/quality-assurance-for-1i8n-in-react
Add blog post 'Quality Assurance for i18n in React'
2 parents dac0bd1 + 01c0297 commit d6fa1e3

File tree

1 file changed

+204
-0
lines changed

1 file changed

+204
-0
lines changed

‎content/blog/quality-assurance-in-i18n-for-react.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
+++
2+
title = "Quality Assurance for i18n in React"
3+
date = 2025-11-01
4+
slug = "quality-assurance-for-i18n-in-react"
5+
tags = ["i18n", "React", "qa"]
6+
summary = "Discover how to achieve quality assurance in React app internationalization by using i18n-check to catch translation issues early, ensuring reliable and consistent multilingual user experiences."
7+
+++
8+
9+
## Introduction
10+
11+
Quality assurance (QA) for internationalization (i18n) means preventing translation errors, missing keys, and inconsistent user experiences across languages. i18n bugs are often hard to detect before production, as they rarely break builds or show up in standard tests, but can quietly impact users at runtime.
12+
13+
Common scenarios include:
14+
15+
- Seeing placeholders like `{user.greeting}` instead of translated text
16+
- Pages crashing due to missing plural forms
17+
- Translation files becoming out of sync, with unused or missing keys
18+
19+
Testing strategies for i18n should be part of your QA process to ensure a consistent experience for all users, regardless of language.
20+
21+
## The problem
22+
23+
Take the following example: the English version of a new product page works perfectly, but a missing translation key in the German locale causes the checkout button to disappear. The tests probably checked for the English version, but never tested if the button is visible when switching to German.
24+
The issue might not be noticeable up until a customer reports that they can't checkout the product.
25+
26+
Internationalization issues usually have multiple possible sources like:
27+
28+
- A translator can forget to translate a key.
29+
- A refactor removes a component but not its translation keys.
30+
- A typo in the key name
31+
32+
There are more scenarios and most can happen more commonly. The issues are similar no matter if working with `i18next`, `react-intl`, `next-intl`, or any JSON-based i18n setup in React.
33+
34+
In this write-up, we'll see how using [`i18n-check`](https://github.com/lingualdev/i18n-check) can make **quality assurance a seamless part of the regular development workflow**, helping to catch any i18n related issues before they hit production.
35+
36+
---
37+
38+
## What is i18n-check?
39+
40+
**i18n-check** is a CLI tool that acts like a **linter for your translation files**.
41+
42+
It scans your app to catch:
43+
44+
- **Missing translations**
45+
- **Invalid ICU syntax**
46+
- **Placeholders that don’t match**
47+
- **Unused or obsolete keys**
48+
- **Keys used in code but missing in your source locale**
49+
50+
It’s currently mainly focused on common React setups.
51+
52+
---
53+
54+
## Getting started with i18n-check in React
55+
56+
### Installation
57+
58+
```bash
59+
npm install --save-dev i18n-check
60+
# or
61+
yarn add -D i18n-check
62+
# or
63+
pnpm add --save-dev @lingual/i18n-check
64+
```
65+
66+
### Translation files setup
67+
68+
Here’s a typical setup:
69+
70+
```bash
71+
locales/
72+
en.json ← source locale (used as reference)
73+
fr.json
74+
de.json
75+
src/
76+
components/
77+
pages/
78+
```
79+
80+
> Tip: Keeping your en.json clean and complete. Think of it as your single source of i18n truth.
81+
82+
### Run checks
83+
84+
```bash
85+
i18n-check --locales locales --source en
86+
```
87+
88+
This will:
89+
90+
- Check every other locale against `en`
91+
92+
- Show you any missing or structurally invalid keys
93+
94+
Output:
95+
96+
```bash
97+
Found missing keys!
98+
┌────────────────────┬────────────────────┐
99+
│ file │ key │
100+
├────────────────────┼────────────────────┤
101+
│ locales/fr.json │ navbar.about │
102+
│ locales/de.json │ footer.contact │
103+
└────────────────────┴────────────────────┘
104+
```
105+
106+
## Catching unused or undefined keys
107+
108+
If you're using `react-intl`, `i18next`, or `next-intl` , i18n-check can parse your source code:
109+
110+
```bash
111+
i18n-check --locales locales --source en -u src -f react-intl
112+
```
113+
114+
This adds two useful checks, that can help with cleaning locale files and catch potential runtime issues:
115+
116+
- **Undefined keys**: used in code, but missing in your source translations
117+
118+
- **Unused keys**: sitting in your .json files, but never referenced in code
119+
120+
Translation files can accumulate unnecessary entries over time like keys from features that have been removed, temporary messages or outdated labels.
121+
122+
This enables to remove these **unused keys**, keeping the translation in sync with the actual code. This not only reduces confusion for translators but also helps prevent accidental re-use of outdated content.
123+
124+
**Before/After Example:**
125+
126+
```json
127+
// Before cleanup
128+
{
129+
"navbar.home": "Home",
130+
"navbar.about": "About",
131+
"oldFeature.unused": "Old feature text",
132+
"temp.message": "Temporary message"
133+
}
134+
135+
// After running i18n-check and removing unused keys
136+
{
137+
"navbar.home": "Home",
138+
"navbar.about": "About"
139+
}
140+
```
141+
142+
## Integrating i18n-check with CI
143+
144+
Integrating i18n-check into your **CI pipeline** will ensure a seamless qa process.
145+
146+
- Run `i18n-check` on every pull request and push to main branches.
147+
- Fail the build if critical translation errors are found.
148+
- Keep your source locale (e.g., en.json) up to date and reviewed.
149+
- Make fixing i18n errors of the review process.
150+
151+
Example of a Github action you can setup:
152+
˘
153+
154+
```yml
155+
# .github/workflows/i18n-check.yml
156+
name: i18n Check
157+
on:
158+
pull_request:
159+
branches:
160+
- main
161+
push:
162+
branches:
163+
- main
164+
165+
jobs:
166+
i18n-check:
167+
runs-on: ubuntu-latest
168+
169+
steps:
170+
- uses: actions/checkout@master
171+
172+
- name: yarn install & build
173+
run: |
174+
yarn install
175+
yarn build
176+
177+
- name: yarn i18n-check
178+
run: |
179+
yarn i18n-check --locales translations/messageExamples --source en-US
180+
```
181+
182+
For more information on how to setup a Github action [check the README](https://github.com/lingualdev/i18n-check?tab=readme-ov-file#as-github-action).
183+
184+
Additionally you can also run it locally with a pre-push or pre-commit hook using Husky.
185+
186+
---
187+
188+
## Customizing i18n-check
189+
190+
`i18n-check` can be customized for the commonly used i18n libraries:
191+
192+
- Supports ICU and i18next formats
193+
- Works with flat or nested JSON structures
194+
- Can ignore certain paths or patterns (`--ignore some.path.*`)
195+
196+
The [README](https://github.com/lingualdev/i18n-check) lists a number of options and possible customizations to help with working with your internationalization.
197+
198+
---
199+
200+
## Summary
201+
202+
Maintaining accuracy and consistency in translation files is essential for reliable multilingual React apps. Using tools like i18n-check as part of your QA process helps teams catch issues early and deliver a better experience for all users.
203+
204+
---

0 commit comments

Comments
 (0)