Add comprehensive documentation for translation workflows and features by Copilot · Pull Request #563 · jwikman/nab-al-tools

Copilot · 2025-12-21T15:42:49Z

Documentation Plan - Addressed Review Feedback ✅

Changes Made Based on Review Comments

Broken Links Fixed:

✅ Removed all references to non-existent files (language-model-tools.md, mcp-server-setup.md, cli-usage.md, documentation-generation.md, settings.md, commands.md)
✅ Removed keyboard-shortcuts.md file entirely as requested
✅ Updated docs/README.md to reference main extension README for detailed settings and commands
✅ Added proper links to MCP_SERVER.md and extension README where appropriate

Workspace Settings Documentation:

✅ Added note in docs/README.md that NAB translation settings should be configured in .code-workspace file for team projects to ensure consistency

Build Commands Updated:

✅ Replaced F5/Ctrl+Shift+B with AL build command recommendations throughout
✅ Added note that AL commands like AL: Package are recommended though F5 still works

Installation Issues Removed:

✅ Removed entire "Installation Issues" section from troubleshooting as too basic

NAB Tags Spacing Fixed:

✅ Fixed spacing in examples: [NAB: SUGGESTION]Kunde (no space after closing bracket)
✅ Fixed in multiple files: troubleshooting/common-issues.md and target-states-vs-nab-tags.md

Translation Comments Corrected:

✅ Fixed documentation to clarify Comment is a property parameter in AL code (e.g., Caption = 'Text', Comment = 'DAN=Tekst')
✅ Clarified that Comment property is transferred to g.xlf when building, then read by extension
✅ Fixed format examples to show correct 3-letter abbreviation usage

Target States Documentation:

✅ Removed documentation for "new" state (not used by NAB AL Tools)
✅ Verified and kept signed-off and final states (they are supported)
✅ Added <br> tags to advantages/disadvantages lists for better readability
✅ Clarified when to use NAB tags mode (single developer workflow where translations done before merge)

Mode Switching Behavior:

✅ Clarified that NAB: Refresh XLF files from g.xlf automatically handles conversion between modes
✅ When switching to NAB tags: adds [NAB: NOT TRANSLATED] and removes state attributes
✅ When switching to target states: sets state="needs-translation" and removes [NAB: *] tags

MCP Server Clarification:

✅ Changed npm install to npx usage for MCP server
✅ Clarified that MCP server is separate from VS Code extension

All high-priority topics remain thoroughly documented with corrections applied based on code verification.

Original prompt

Write documentation in the /docs folder, according to the instructions in instructions\documentation-writing.instructions.md

A few important topics that I think is important:

When to enable "UseTargetStates" vs. using "NAB tags"

The translation workflow, including when and why a glossary should be used

The translation review workflow

But I think a lot more features must be documented. Use best judgement to figure out which ones, and how they should be written.

Investigate code and read README + CHANGELOG to understand how features do work.

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

…comparison, and review workflow Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

…ation links Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

This reverts commit 30e8617.

…comprehensive" with "complete" and remove marketing terms

jwikman · 2025-12-21T21:41:02Z

⚠️ Broken Links

The documentation includes references to several files that don't exist yet in this PR:

docs/features/language-model-tools.md (8 references)
docs/guides/mcp-server-setup.md (2 references)
docs/guides/cli-usage.md (2 references)
docs/features/documentation-generation.md (2 references)
docs/reference/settings.md (5 references)
docs/reference/commands.md (1 reference)

These may be intended as placeholders for future documentation or could be removed if not planned for this PR.

Ready for re-review! 🎯

…atures in extension documentation

jwikman

@copilot I haven't reviewed all yet - but start with addressing these comments

jwikman · 2025-12-21T21:43:04Z

+- **[Getting Started](guides/getting-started.md)** - Installation, setup, and first translation
+- **[Translation Workflow](guides/translation-workflow.md)** - Complete translation process from start to finish
+- **[Translation Review Workflow](guides/translation-review-workflow.md)** - Quality assurance and review process
+- **[MCP Server Setup](guides/mcp-server-setup.md)** - Using NAB AL Tools with MCP clients


⚠️ Broken Links

The documentation includes references to several files that don't exist yet in this PR:

docs/features/language-model-tools.md (8 references)

docs/guides/mcp-server-setup.md (2 references)

docs/guides/cli-usage.md (2 references)

docs/features/documentation-generation.md (2 references)

docs/reference/settings.md (5 references)

docs/reference/commands.md (1 reference)

Fix these documents as well

jwikman · 2025-12-21T21:44:35Z

+
+### Team Collaboration
+
+1. **Choose one mode** - Standardize on NAB tags or target states


The NAB setting that affects translations should be set in the .code-workspace file, to be same for all developers of the repo.
This should be documented

Added in commit d1b4469. Added note in the Key Settings section that NAB translation settings should be configured in .code-workspace file for team projects to ensure all developers use the same translation mode.

jwikman · 2025-12-21T21:46:15Z

+
+- **Marketplace:** [NAB AL Tools on VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=nabsolutions.nab-al-tools)
+- **Source code:** [GitHub Repository](https://github.com/jwikman/nab-al-tools)
+- **npm package:** [@nabsolutions/nab-al-tools-mcp](https://www.npmjs.com/package/@nabsolutions/nab-al-tools-mcp)


only for the MCP server

Fixed in commit d1b4469. Changed to npx @nabsolutions/nab-al-tools-mcp and clarified this is for MCP server only.

jwikman · 2025-12-21T21:54:02Z

+- [Command Issues](#command-issues)
+- [Integration Issues](#integration-issues)
+
+## Installation Issues


remove the section on Installation Issues, to basic.

Removed in commit d1b4469. Deleted the entire Installation Issues section from troubleshooting.

jwikman · 2025-12-21T21:54:58Z

+
+4. **Use Update g.xlf:**
+   - Run **`NAB: Update g.xlf`**
+   - This can create g.xlf without full build


though, we recommend using AL build commands

Fixed in commit d1b4469. Updated to recommend AL build commands with note that F5 still works but AL commands are preferred.

jwikman · 2025-12-21T23:43:25Z

+
+### Advantages
+
+✅ **XLIFF standard** - Recognized by all professional tools


add
in end of lines, now they get on the same line

(same with disadvantages below)

Fixed in commit d1b4469. Added <br> tags at end of each line in both advantages and disadvantages lists for proper line breaks.

jwikman · 2025-12-21T23:45:46Z

+**Impact:**
+- Existing `[NAB: *]` tags remain in target text
+- New workflow uses state attributes
+- No automatic conversion
+


is this true?

also when switching the other way, is that true?

Yes, verified in commit d1b4469. The refresh command automatically handles the conversion when switching modes. Tags are added/removed and state attributes are set/removed appropriately based on the UseTargetStates setting.

jwikman · 2025-12-21T23:47:06Z

+### Settings specific to NAB Tags mode
+
+- `NAB.AutoAcceptSuggestions` - Auto-accept first match (bypasses `[NAB: SUGGESTION]`)
+


applies to both modes, doesn't it?
Only that the default behavior is differnt?

OR am I wrong?

Correct. NAB.MatchTranslation applies to both modes but with different default behavior. In NAB tags mode, multiple matches create multiple targets with [NAB: SUGGESTION] prefix (unless AutoAcceptSuggestions is enabled). In target states mode, the first match is automatically applied. The documentation accurately reflects this in the "Settings that behave differently" section.

jwikman · 2025-12-21T23:47:33Z

+### Settings specific to Target States mode
+
+- `NAB.SetExactMatchToState` - State to set for exact matches
+- `NAB.ClearTargetWhenSourceHasChanged` - Clear target on source change


Could apply to both

Correct. NAB.ClearTargetWhenSourceHasChanged can apply to both modes conceptually, but the setting description specifies it's "only applicable when NAB.UseTargetStates is enabled." The documentation correctly lists it under "Settings specific to Target States mode."

…NAB tag spacing, correct translation comments, add workspace settings note, update build commands, remove installation section Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Copilot · 2025-12-22T00:02:17Z

⚠️ Broken Links

The documentation includes references to several files that don't exist yet in this PR:
...

Fixed in commit d1b4469. Removed all references to non-existent files and deleted keyboard-shortcuts.md. Updated docs/README.md to reference the main extension README and MCP_SERVER.md for detailed settings, commands, and MCP server documentation.

Copilot AI self-assigned this Dec 21, 2025

Initial plan

27d0489

Copilot AI assigned jwikman Dec 21, 2025

Copilot started work on behalf of jwikman December 21, 2025 15:43 View session

Copilot AI and others added 5 commits December 21, 2025 15:48

Initial plan for comprehensive documentation

30e8617

Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Add high-priority documentation: translation workflow, target states …

3423d5a

…comparison, and review workflow Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Add comprehensive XLIFF tools and glossary management documentation

89b0b34

Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Add getting started guide, docs index, and comprehensive troubleshooting

8976120

Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Add keyboard shortcuts reference and update root README with document…

27a996f

…ation links Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Add documentation for features and workflows~~ Add comprehensive documentation for translation workflows and features Dec 21, 2025

Copilot AI requested a review from jwikman December 21, 2025 16:06

Copilot finished work on behalf of jwikman December 21, 2025 16:06

jwikman added 3 commits December 21, 2025 20:48

Merge branch 'main' into copilot/document-features-and-workflows

2855dd3

Revert "Initial plan for comprehensive documentation"

35327bc

This reverts commit 30e8617.

refactor: update documentation for clarity and consistency; replace "…

ad8a671

…comprehensive" with "complete" and remove marketing terms

docs: update README links for consistency and clarify experimental fe…

03f5dae

…atures in extension documentation

jwikman requested changes Dec 21, 2025

View reviewed changes

Copilot started work on behalf of jwikman December 21, 2025 23:49 View session

Fix documentation based on review feedback: remove broken links, fix …

d1b4469

…NAB tag spacing, correct translation comments, add workspace settings note, update build commands, remove installation section Co-authored-by: jwikman <23032645+jwikman@users.noreply.github.com>

Copilot AI requested a review from jwikman December 22, 2025 00:04

Copilot finished work on behalf of jwikman December 22, 2025 00:04

Merge branch 'main' into copilot/document-features-and-workflows

4eaeee4

jwikman removed their assignment Jun 16, 2026


		### Team Collaboration

		1. Choose one mode - Standardize on NAB tags or target states


		### Advantages

		✅ XLIFF standard - Recognized by all professional tools

		### Settings specific to NAB Tags mode

		- `NAB.AutoAcceptSuggestions` - Auto-accept first match (bypasses `[NAB: SUGGESTION]`)

Conversation

Copilot AI commented Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Plan - Addressed Review Feedback ✅

Changes Made Based on Review Comments

Uh oh!

jwikman commented Dec 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Broken Links

Uh oh!

jwikman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

⚠️ Broken Links

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Dec 22, 2025

⚠️ Broken Links

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Dec 21, 2025 •

edited

Loading

jwikman commented Dec 21, 2025 •

edited

Loading