feat(spec): improve error messages for invalid locale codes

[jaya6400]

Summary

• This PR improves the error message shown when a user specifies an unsupported or invalid locale code in their i18n.json config. Instead of a generic Zod validation error, the parser now extracts and displays the exact invalid locale value, making the error more actionable.

• Crucially, this PR does not change any validation behavior – only the error message is improved. The parser continues to throw only for invalid locale codes (same as main), and all other validation issues (missing source, unknown bucket types, etc.) still attempt an upgrade.

Changes:

• Added isLocaleError helper to cleanly identify Zod issues related to invalid locale codes.

• Added getValueAtPath helper to safely extract the actual invalid locale value from the raw config object.

• Updated the parse function in extendConfigDefinition to build error messages that include the unsupported locale(s), e.g.:

Unsupported locale: xxxx

instead of a generic Zod message.

• Removed the mistakenly added missing‑source hard error (which would have been a breaking change) – validation logic now matches main exactly.

Testing

Logic tests added:

• should throw an error for unsupported locales – verifies that multiple invalid locales are reported in the error message with their values.

• should throw for invalid locale codes with clear error – confirms that a single invalid locale displays the exact value.

• should parse the default config without errors – ensures the built‑in default config is still accepted.

• Existing upgrade tests (v0 → latest, v1 → latest) pass, verifying backward compatibility.

All 34 unit tests in @lingo.dev/_spec pass locally.

Checklist:

• Changeset added – included as @lingo.dev/_spec patch bump.

• Tests cover business logic (not just happy path) – the added tests explicitly cover invalid locale edge cases and ensure no regression.

• No breaking changes – validation behavior is identical to main. Only the error message is improved.

Closes #561

Summary by CodeRabbit

• Bug Fixes
  • Invalid locale code error messages now display the unsupported locale value, providing clearer feedback when configuration validation fails.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2bbff640-73eb-4bf0-a6e7-408cf595a277

📥 Commits

Reviewing files that changed from the base of the PR and between a4664c9 and c95a703.

📒 Files selected for processing (3)

• .changeset/improve-config-validation-errors.md
• packages/spec/src/config.spec.ts
• packages/spec/src/config.ts

---

📝 Walkthrough

Walkthrough

Adds two internal helper functions (isLocaleError, getValueAtPath) to config.ts and updates the locale error path to extract and display the invalid locale value in error messages. Tests are extended to cover defaultConfig, minimal version configs, and the new Unsupported locale: <value> message. A patch changeset entry is included.

Changes

Locale validation error improvement

Layer / File(s)	Summary
Internal helpers and updated error construction packages/spec/src/config.ts	Adds isLocaleError to detect locale-related Zod issues by message text, and getValueAtPath to safely traverse a nested unknown object along a Zod issue path. Updates the locale-error block to call these helpers, replacing an inline includes predicate and a manual path reduction over rawConfig.locale.
Tests and changeset packages/spec/src/config.spec.ts, .changeset/improve-config-validation-errors.md	Adds createLatestConfig helper and new test cases asserting parseI18nConfig accepts defaultConfig, accepts minimal version: 0 and version: 1 configs, and throws with the message Unsupported locale: xxxx for invalid locale codes. Adds a patch changeset entry for @lingo.dev/_spec.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers

• cherkanovart
• AndreyHirsa

Poem

🐇 Hop hop, the locale said "xxxx"—
No more vague errors, the message is clear!
A path through the config, a value retrieved,
"Unsupported locale" is now well-received.
The rabbit approves, with a wiggle of cheer! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: improving error messages for invalid locale codes in the spec package.
Description check	✅ Passed	The description comprehensively covers the summary, changes, testing approach, and includes all required checklist items with appropriate context about behavior preservation.
Linked Issues check	✅ Passed	The PR directly addresses issue #561 by improving error message descriptiveness in config validation, providing exact invalid locale values instead of generic Zod errors.
Out of Scope Changes check	✅ Passed	All changes are focused on improving error messages for invalid locale codes; no unrelated modifications or scope creep detected in the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed: private package registry requires authentication. Disable ESLint in CodeRabbit settings or use public packages.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jaya6400]

Hey @moygospadin, I've reworked the changes based on your feedback from #2112 (comment). This new PR (#2144) only improves error messages and removes all the strict validation rules that were causing breaking changes. The default config now parses correctly, and the error string duplication is fixed.
Please review the changes, let me know if any further changes required. Thanks!
@cherkanovart @maxprilutskiy

[jaya6400]

Hi @moygospadin , I see one CI check is failing, I checked it is a pre existed failure on "main" branch as well not related to my changes.
Is there any update on this PR review, do I need to make any further changes?
@maxprilutskiy @cherkanovart @AndreyHirsa

[AndreyHirsa]

Hey @jaya6400, thanks for sticking with this! I dug into the current diff and it actually comes out behavior-identical to main — it already throws Unsupported locale: <value> on this path, so this version ends up being a refactor rather than a new message (and a few of the tests overlap with the existing upgrade v0/v1 / unsupported locales ones). I'll leave the PR open, but rather than iterate on code, let's first agree on what should improve over on #561 — which cases to cover and the exact messages, kept non-breaking. Once we're aligned I'll happily review the change here. 🙏