Комментарии переводчика, контекст и стабильные ключи часто не попадают в плоский CSV, хотя без них невозможно корректно перевести строку. При обратном импорте система создает новые записи или перезаписывает существующие. Надежный экспорт должен поддерживать полный round trip: export и import без изменений не меняют данные.

Создайте маленький эталон с обычной строкой, plural forms, переносом, HTML, контекстом и комментарием. Выполните export, затем import в копию проекта и сравните структурный результат. Не проверяйте формат простым сравнением текста файлов.

Что проверить в первую очередь

Начните с одного воспроизводимого сценария. Зафиксируйте точное время, идентификатор объекта, пользователя или операции, версию приложения и последнее известное рабочее состояние. Не меняйте несколько параметров одновременно: один контролируемый шаг должен подтверждать или исключать одну гипотезу. Перед работой с данными и конфигурацией подготовьте резервную копию и проверенный способ отката.

  • Уточните исходный и целевой форматы и какие поля каждый реально поддерживает.
  • Проверьте стабильный ID, key, namespace, context и locale каждой записи.
  • Сохраните комментарии разработчика и переводчика раздельно, если система их различает.
  • Проверьте plural categories, placeholders и ICU-сообщения.
  • Убедитесь в UTF-8, BOM, экранировании кавычек и переносов строк.

Почему возникает проблема

Внешний симптом часто появляется дальше по цепочке, чем первичная ошибка. Интерфейс может показывать неверное состояние из-за backend, очереди, кеша, прав доступа, фоновой задачи или внешнего API. Поэтому важно проследить данные от источника до результата и найти первую точку расхождения, а не исправлять только последнее сообщение об ошибке.

  • Экспортер берет только отображаемый текст и перевод, пропуская метаданные.
  • CSV-колонки сопоставляются по позиции, а не по заголовку и версии схемы.
  • При flatten вложенного JSON теряются namespace или экранированные точки ключа.
  • Комментарий существует только в памяти парсера и не входит в выходную модель.
  • Импорт ищет запись по source text, который не является стабильным идентификатором.

Пошаговая диагностика

Диагностику проводите на тестовой записи или отдельном окружении. В журналах скрывайте токены, пароли, персональные данные и содержимое документов. Для каждого шага сохраняйте измеримый результат: код ответа, версию записи, идентификатор события, состояние процесса, контрольную сумму или время выполнения. Так можно отличить подтвержденную причину от случайного совпадения.

  • Посчитайте записи и уникальные ключи до экспорта и после обратного импорта.
  • Сравните структурные поля эталона, включая null, пустую строку и отсутствующее значение.
  • Проверьте конфликтующие ключи из разных namespace и контекстов.
  • Протестируйте кавычки, запятые, переносы, emoji и нелатинские символы.
  • Найдите этап pipeline, где метаданные исчезают: parser, domain model, serializer или importer.

Контракт формата локализации

Перед конвертацией полезно описать внутреннюю каноническую запись, которая не зависит от конкретного файла.

  • Запись содержит stable ID, key, namespace, locale, source и translation.
  • Context и comments являются отдельными полями, а не частью текста.
  • Plural forms и placeholders представлены структурно.
  • Сериализатор явно сообщает о неподдерживаемых полях целевого формата.
  • Файл содержит версию схемы и детерминированный порядок для понятного diff.

Как исправить проблему

Исправление делите на небольшие обратимые изменения. Сначала устраните подтвержденную причину, затем повторите исходный сценарий и проверьте соседние функции. Массовое обновление данных запускайте на ограниченной выборке с отчетом и только после сверки расширяйте на весь объем. Не отключайте авторизацию, проверку сертификатов, валидацию или аудит ради быстрого исчезновения симптома.

  • Расширьте внутреннюю модель и exporter недостающими ключами и комментариями.
  • Добавьте обязательные именованные колонки и версию CSV-схемы.
  • Используйте безопасное кодирование вложенных ключей вместо неоднозначного split по точке.
  • При потере возможностей формата создавайте sidecar metadata либо блокируйте экспорт с отчетом.
  • Импортируйте по stable ID или составному ключу namespace и key, а не по исходной фразе.

Безопасный порядок внедрения

  • Сохраните затрагиваемые данные, конфигурацию и текущие журналы, затем проверьте возможность реального восстановления.
  • Повторите проблему на тестовом объекте без реальных списаний, рассылок и необратимых изменений клиентских данных.
  • Зафиксируйте изменение в системе контроля версий или журнале работ вместе с причиной, ожидаемым эффектом и планом отката.
  • Проведите тест на нормальном сценарии, ошибочном вводе, повторном запросе, параллельной операции и временной недоступности зависимости.
  • После выпуска наблюдайте полный пользовательский путь, логи и метрики, а не только один успешный запрос.

Как проверить результат

Разовый успешный тест недостаточен. Повторите операцию, проверьте крайние значения, одновременные действия и восстановление после перезапуска или временного сбоя. Для важного сценария сохраните автоматический тест либо короткий регрессионный чек-лист. Итог должен подтверждаться не только интерфейсом, но и состоянием базы, очереди, внешнего сервиса и журналом действий.

  • Export и import без редактирования сохраняют число записей и все поля эталона.
  • Повторный экспорт дает детерминированный файл без случайного перемешивания.
  • Plural forms и placeholders проходят валидацию.
  • Конфликтующие namespace не склеиваются.
  • Неподдерживаемые метаданные перечисляются до потери данных.

Типичные ошибки при исправлении

  • Использовать source text как уникальный ключ.
  • Тихо отбрасывать комментарии, потому что целевой формат их не поддерживает.
  • Разбирать CSV через split по запятой.
  • Нормализовать пробелы и переносы внутри переводимых строк без правила.
  • Перезаписывать базу импортом без предварительного diff и резервной копии.

Как предотвратить повторение

Профилактика строится вокруг явных контрактов, повторяемых релизов и наблюдаемости. Система должна не только работать сейчас, но и позволять быстро увидеть нарушение правила при следующем обновлении, росте нагрузки или сбое внешнего сервиса. Проверки особенно полезно автоматизировать там, где ошибка уже привела к потере времени, данных, денег или заявок.

  • Храните эталонные round-trip тесты для каждого формата.
  • Версионируйте схему экспорта и правила миграции.
  • Показывайте dry-run импорта с созданными, измененными и конфликтными ключами.
  • Проверяйте placeholders и plural categories в CI.
  • Сохраняйте резервную копию и журнал автора импортной операции.

Что контролировать после выпуска

  • Количество успешных и ошибочных операций в разрезе версии, канала и типа сценария.
  • Возраст необработанных записей, длину очередей, число повторных попыток и долю окончательных отказов.
  • Расхождение между пользовательским статусом и фактическим состоянием в базе или внешней системе.
  • Появление новых кодов ошибок после релиза и изменение времени выполнения ключевой операции.
  • Сигналы от поддержки и бизнес-метрики, которые могут показать скрытый частичный сбой.

Что подготовить для технического разбора

  • Описание ожидаемого и фактического поведения с точной последовательностью действий.
  • Время проблемы, идентификатор тестового объекта и версии затронутых компонентов.
  • Фрагменты журналов до и после ошибки без секретов и персональных данных.
  • Перечень последних изменений и уже выполненных проверок.
  • Безопасный доступ к тестовой среде либо способ воспроизвести сбой без влияния на клиентов.

Частые вопросы

Можно ли сохранить комментарии в CSV?

Да, отдельными колонками с корректным CSV-сериализатором, если схема и импорт согласованы.

Почему нельзя искать строку по исходному тексту?

Текст может повторяться и изменяться, поэтому он не является стабильной идентичностью записи.

Что делать, если формат не поддерживает метаданные?

Использовать sidecar-файл, более богатый формат или явно предупреждать и блокировать потенциально разрушающий round trip.

Когда нужна помощь специалиста

Если конвертер локализации теряет ключи или контекст, я могу построить каноническую модель, исправить export и import и добавить round-trip тесты. Для оценки нужны примеры исходного и поврежденного файла без закрытых текстов.