Начните с одного текста, который точно работал до релиза. Найдите его message key в исходном коде и в каталоге нужной locale, затем проверьте собранный артефакт на сервере. Если перевод есть в репозитории, но отсутствует в artifact, проблема не у переводчика — его исключила сборка или неверный glob.

Три симптома означают разное: видимый key указывает на отсутствие сообщения, старый перевод — на кеш или старый bundle, а исходный язык только у новых строк — на неполный merge каталога. Массовая ручная правка текстов до этого диагноза обычно усложняет откат.

Один ключ проходит пять контрольных точек

ТочкаЧто ищемЕсли значения нет
Source extractionКлюч и актуальный default messageExtractor не видит файл или динамический ключ
Locale catalogПеревод и статус не fuzzyКаталог не смержен с новым шаблоном
Compiled bundleКлюч после компиляцииРесурс исключён из build или compilation failed
Deploy manifestНовый hash locale-файлаСервер обслуживает предыдущий artifact
Runtime responseНужная locale и свежий ETagFallback, 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 через используемую библиотеку, не зашивайте правило условием на последнюю цифру.

Кеш сбрасывается версией ресурса

  1. Собрать locale bundle и вычислить новый content hash.
  2. Включить hash в manifest или имя файла.
  3. Развернуть HTML и bundle в согласованном порядке.
  4. Проверить ETag и содержимое через публичный CDN.
  5. Открыть старую сессию и убедиться, что service worker забрал новый manifest.

Откат возвращает согласованный комплект

Не откатывайте только JavaScript, оставляя новый каталог, или наоборот. Версия приложения, message schema и ресурсы locale составляют один release. Для разбора сохраните commit, locale, broken key, исходный pattern, перевод, hash bundle и response headers — этого достаточно, чтобы найти стадию, где перевод исчез.

Проверенные источники