Начните с одного текста, который точно работал до релиза. Найдите его message key в исходном коде и в каталоге нужной locale, затем проверьте собранный артефакт на сервере. Если перевод есть в репозитории, но отсутствует в artifact, проблема не у переводчика — его исключила сборка или неверный glob.
Три симптома означают разное: видимый key указывает на отсутствие сообщения, старый перевод — на кеш или старый bundle, а исходный язык только у новых строк — на неполный merge каталога. Массовая ручная правка текстов до этого диагноза обычно усложняет откат.
Один ключ проходит пять контрольных точек
| Точка | Что ищем | Если значения нет |
|---|---|---|
| Source extraction | Ключ и актуальный default message | Extractor не видит файл или динамический ключ |
| Locale catalog | Перевод и статус не fuzzy | Каталог не смержен с новым шаблоном |
| Compiled bundle | Ключ после компиляции | Ресурс исключён из build или compilation failed |
| Deploy manifest | Новый hash locale-файла | Сервер обслуживает предыдущий artifact |
| Runtime response | Нужная locale и свежий ETag | Fallback, CDN или service worker отдаёт старую версию |
GNU gettext разделяет шаблон сообщений, редактируемые PO-каталоги и скомпилированные MO-файлы; другие системы имеют аналогичные стадии. Обновление исходников без merge и компиляции не меняет production. Зафиксируйте конкретную команду локализации в CI, а не выполняйте её вручную на сервере.
Сверка ключей входит в сборку
sourceKeys = extractMessageKeys(sourceTree)
localeKeys = readLocaleCatalog("ru")
missing = sourceKeys - localeKeys
orphaned = localeKeys - sourceKeys
failBuildIf(missing intersects criticalMessageKeys)
report(missing, orphaned)Не все отсутствующие переводы обязаны блокировать релиз, но сообщения оплаты, авторизации, ошибок и согласий лучше считать критическими. Отдельно запрещайте динамическое составление key из пользовательских данных: extractor не может заранее перечислить такие варианты.
Placeholders проверяются как контракт
- Набор placeholders в переводе должен совпадать с исходным сообщением.
- Переменную можно переставить по правилам языка, но нельзя удалить или переименовать случайно.
- Предложение с переменными переводится целиком, а не склеивается из отдельных фрагментов.
- HTML и rich-text markers проходят отдельную проверку разрешённых тегов.
- Дата, число и валюта форматируются locale-aware библиотекой, а не вручную внутри строки.
ICU MessageFormat предназначен для сообщений, где переводчик может менять порядок аргументов. Если после обновления библиотека стала строже разбирать кавычки или braces, ошибка должна проявиться в compile step, а не у посетителя в браузере.
Plural-формы тестируем числами языка
Категории plural зависят от locale и не сводятся к единственному/множественному числу. Для русского проверьте значения, попадающие в one, few, many и other, включая дроби, если продукт их показывает. Берите категории из CLDR через используемую библиотеку, не зашивайте правило условием на последнюю цифру.
Кеш сбрасывается версией ресурса
- Собрать locale bundle и вычислить новый content hash.
- Включить hash в manifest или имя файла.
- Развернуть HTML и bundle в согласованном порядке.
- Проверить ETag и содержимое через публичный CDN.
- Открыть старую сессию и убедиться, что service worker забрал новый manifest.
Откат возвращает согласованный комплект
Не откатывайте только JavaScript, оставляя новый каталог, или наоборот. Версия приложения, message schema и ресурсы locale составляют один release. Для разбора сохраните commit, locale, broken key, исходный pattern, перевод, hash bundle и response headers — этого достаточно, чтобы найти стадию, где перевод исчез.