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_file → locale_directoryFull rebuild; set structure explicitly
Edit target locale JSON onlyReuse analysis (target locale only)
Edit source locale JSON onlyPartial missingKeys refresh

See also ​