feat(transloco): add TranslationLoadError class for translation load failures

[arturovt]

Replace the generic Error thrown in handleFailure with a dedicated TranslationLoadError class. The new class exposes structured metadata (lang, fallbackLangs, isScope) for easier error handling and logging, and sets a descriptive name property for clearer stack traces.

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://github.com/jsverse/transloco/blob/master/CONTRIBUTING.md#commit

PR Type

What kind of change does this PR introduce?

• Feature

Does this PR introduce a breaking change?

• Yes
• No

---

Summary by cubic

Add TranslationLoadError for failed translation loads, replacing the generic Error. Exposes lang, fallbackLangs, and isScope for clearer debugging and handling.

• New Features
  • Introduced TranslationLoadError(lang, fallbackLangs, isScope) with a descriptive message and name; hints at scope typos when relevant.
  • Thrown by TranslocoService when all fallbacks fail; exported from index.ts for app-level handling.

^{Written for commit 1fc5306. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Added a new TranslationLoadError type that's exposed by the library. It provides richer diagnostics for translation load failures—including which language failed, fallback languages attempted, and whether a scoped translation was involved—to improve error handling and debugging.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new exported error class TranslationLoadError to the Transloco service and replaces generic error throws with this structured error to convey language, fallback languages, and scope information when translation loading fails.

Changes

Cohort / File(s)	Summary
Public API Exports libs/transloco/src/index.ts	Adds TranslationLoadError to the public exports alongside translate and TranslocoService.
Error Handling libs/transloco/src/lib/transloco.service.ts	Introduces export class TranslationLoadError extends Error with lang, fallbackLangs, and isScope fields; replaces generic Error throws in translation load failure paths with TranslationLoadError.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A little hop, I code and cheer,
When translations fail and paths aren't clear,
I bring the lang, the fallbacks too,
And hint if scope is in the view,
Now errors tell the tale anew.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing a dedicated TranslationLoadError class to replace generic Error handling for translation load failures.
Description check	✅ Passed	PR description covers core requirements but is missing some template elements like test confirmation and documentation updates.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@jsverse/transloco

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco@906

@jsverse/transloco-locale

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-locale@906

@jsverse/transloco-messageformat

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-messageformat@906

@jsverse/transloco-optimize

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-optimize@906

@jsverse/transloco-persist-lang

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-persist-lang@906

@jsverse/transloco-persist-translations

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-persist-translations@906

@jsverse/transloco-preload-langs

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-preload-langs@906

@jsverse/transloco-schematics

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-schematics@906

@jsverse/transloco-scoped-libs

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-scoped-libs@906

@jsverse/transloco-utils

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-utils@906

@jsverse/transloco-validator

npm i https://pkg.pr.new/jsverse/transloco/@jsverse/transloco-validator@906

commit: 1fc5306

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@libs/transloco/src/lib/transloco.service.ts`:
- Around line 92-105: The error message in the TranslationLoadError constructor
contains a grammatical typo ("did you misspelled the scope name?"); update the
message assembly in the TranslationLoadError constructor (when isScope is true)
to use the correct form, e.g. "did you misspell the scope name?" so the thrown
error text is grammatically correct and still includes the scope hint.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ee8ff0e0-f1f4-41e9-845e-6ecef653857f

📥 Commits

Reviewing files that changed from the base of the PR and between 7989622 and b5e4505.

📒 Files selected for processing (2)

• libs/transloco/src/index.ts
• libs/transloco/src/lib/transloco.service.ts

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="libs/transloco/src/lib/transloco.service.ts">

<violation number="1" location="libs/transloco/src/lib/transloco.service.ts:100">
P3: Grammar error: "did you misspelled" should be "did you misspell". Since this is a user-facing error message, it's worth fixing.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[shaharkazaz]

@arturovt Netanel isn't part of this project for a long time now.
It's maintained soly by me ATM, let's discuss a collaboration as my availability isn't as it used to.

[arturovt]

@shaharkazaz do you have a slack where we could chat or may be google chat?

[shaharkazaz]

X, google, discord all are fine

[arturovt]

sent you a message on google chat