Skip to content

docs: add translation model installation guide and fix plan for #6#7

Open
dskarasev wants to merge 1 commit into
PangMo5:mainfrom
dskarasev:fix/translate-unable-to-translate-error
Open

docs: add translation model installation guide and fix plan for #6#7
dskarasev wants to merge 1 commit into
PangMo5:mainfrom
dskarasev:fix/translate-unable-to-translate-error

Conversation

@dskarasev

Copy link
Copy Markdown

Summary

Add comprehensive user documentation and implementation plan for fixing the 'Unable to translate' error in translation feature.

Changes

  • README.md: Add Troubleshooting section with quick steps to install translation language models
  • docs/LANGUAGE_MODELS.md: New detailed guide covering:
    • How translation models work on macOS
    • Step-by-step installation via System Settings
    • Verification and language selection
    • Troubleshooting for common issues
    • Advanced terminal commands
  • docs/plans/2026-06-13-001-fix-unable-to-translate-bug-plan.md: Implementation plan including:
    • Root cause analysis (missing language models on device)
    • 6 implementation units for fixing error handling and improving UX
    • Consistent error handling between live overlay and region capture
    • Test scenarios and verification strategy

Why

The translation feature fails with "Unable to translate" when a language's translation model isn't installed on the Mac. This PR provides:

  1. Immediate user guidance via README and docs so users can fix the issue now
  2. Implementation plan for improving in-app error messages to point users to these docs
  3. Root cause analysis from code investigation (per-line language detection can resolve to uninstalled models)

Related

Fixes #6

Testing

  • User can read README → Troubleshooting and follow steps to install language models
  • docs/LANGUAGE_MODELS.md provides detailed guidance for various scenarios
  • Implementation plan is ready for code changes in follow-up PR

…o5#6

Add comprehensive user documentation for installing macOS translation
language models, which are required by the Apple Translation framework.
Include:
- Troubleshooting section in README with quick steps
- Detailed guide in docs/LANGUAGE_MODELS.md with multiple scenarios
- Implementation plan (docs/plans/) for improving in-app error messages
  to guide users to this documentation

Fixes PangMo5#6 by providing immediate user guidance while the code fix is
being implemented to make error messages more helpful.
@PangMo5 PangMo5 self-requested a review June 15, 2026 01:53
@PangMo5 PangMo5 added the documentation Improvements or additions to documentation label Jun 15, 2026
@PangMo5

PangMo5 commented Jun 15, 2026

Copy link
Copy Markdown
Owner

Thanks a lot for your first contribution!
LGTM 👍

Some context on the plan for when the actual code work happens:

  • RegionCaptureFeature already has lastError, but RegionResultView renders imageData first, so a translation error doesn't really reach that branch as-is.
  • TranslationError is already a type in the Translation framework, so there'd be a name clash with a new one.
  • Root cause looks right. One thing to note: downloading a missing language goes through a translationTask session (prepareTranslation) rather than installedSource, so it's a bit more involved than just the error message.
  • Minor: since this is docs-only, Refs #6 might fit better than Fixes #6.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Translation feature displays 'Unable to translate' error

2 participants