Skip to content

Locale layout mismatch rebuild

Problem

Changing locales.mode, locales.structure, or locales.directory without clearing cache can leave files.json fingerprints pointing at the wrong segment set. Operators may see stale missingKeys or validate results until something forces a rescan.

What we do

  1. Layout fingerprint in files.json records mode, structure, directory, and source.
  2. On mismatch vs live config, decideAnalysisRebuild returns full with reason layout_changed — full project scan, not a partial src patch.
  3. Partial layout recovery: when only the fingerprint changes but src index is still usable, core may re-walk locale segments and reuse the cached src/** index where safe (CLI cache).
  4. --debug-cache: look for analysis rebuild: full (...) including layout-related reasons after config edits.

Operator checklist

ChangeExpected cache behavior
Rename locales.directoryFull rebuild on next command
Switch flat_filelocale_directoryFull rebuild; set structure explicitly
Edit target locale JSON onlyReuse analysis (target locale only)
Edit source locale JSON onlyPartial missingKeys refresh

See also