Skip to main content

How to Display JSON Comments and Reference Images in the Editor

How to Display JSON Comments and Reference Images in the Editor

When localizing JSON software strings, developers frequently attach segment-level context — design notes, character limits, or mockup links — directly inside the JSON file, under a comments property. In wxrks, you can automatically surface these developer comments and any reference images they link to directly inside the Editor and Review workspaces, and optionally feed that context into Context Sensitive (CS) AI translation.

Audience & Prerequisites

  • Target Audience: Account Admins, Project Managers, and Vendors (Translators and Reviewers).

  • Permissions Required:

  • Configure the JSON parser options: Account Admin or Project Manager permission to create projects or import files.

  • Toggle comment visibility in the Editor: the Edit Visibility Comments permission (People > Users > [User] > Permissions > Editor). Without it, the visibility checkbox is locked (view-only).

  • Supported File Types: .json files where segments carry a comments string alongside their source text.

Table of Contents

Key Concepts

Concept

Description

comments property

A string field in your JSON objects holding developer notes, instructions, or image URLs.

Show Comments In The Editor

JSON filter setting. When enabled, comments and any reference images they contain are shown to translators and reviewers in the Editor and Review workspaces.

Use Comments In CS

JSON filter setting. When enabled, comment text (with any image URLs stripped) is sent to Context Sensitive (CS) AI translation as additional guidance, truncated to 400 characters.

Reference image

An image automatically downloaded from an https:// URL found inside a comment, so translators see the visual context without leaving the segment.

Example: a comments property sits alongside source and target in the same JSON object:

{
  "checkout-submit-button": {
    "source": "Place Order",
    "target": "",
    "comments": "Button label on final checkout step. Keep under 15 characters. Reference mockup: https://example.com/images/checkout-btn.png"
  }
}

Nested keys and array items — such as item.comments or items[0].comments — are detected the same way.

Step 1: Enable the JSON Comment Options

Comment extraction is off by default. It's a per-file parser option that you set the moment you upload a .json file — for example, while creating a new project.

  1. Start creating a project (Projects > New Project > Create a Direct Project) and reach the Upload Files step. Add your .json file.

  2. Click the file's type icon to expand its parser options.

Screenshot of the wxrks project creation Upload Files step, with the JSON file's type icon highlighted in a red box next to the uploaded json-comments-test-samples.json file.

  1. Scroll to Options > Flags and set: * Show Comments In The Editor — turn on to display developer comments and reference images to translators and reviewers. * Use Comments In CS — turn on if AI-assisted translation (Initial AI Translation, MT augmentation, Sous Chef, TM, and Glossary prompts) should also read comment instructions.

Screenshot of the wxrks JSON parser Options panel during project creation, with the "Show Comments In The Editor" toggle (badge 1) and "Use Comments In CS" toggle (badge 2) both enabled and highlighted in red boxes under Options > Flags.

ℹ️ Note: These two toggles are independent — you can show comments to human linguists without sending them to AI, or the reverse.

  1. Continue the project creation wizard as normal. The setting applies only to the file(s) uploaded in this step; it does not retroactively affect files already segmented in existing projects.

💡 Tip: Click Save filter (the floppy-disk icon next to the Filters dropdown) to save this configuration under a name instead of rebuilding it on every project. Saved filters are managed under Organizations > Organizational Units > [Unit] > Project tab > Filter Settings, and appear in the Filters dropdown so any future project in that Organizational Unit can reuse them with one click.

Step 2: Upload and Process the JSON File

  1. Upload your .json file (for example, json-comments-test-samples.json) to the project.

  2. During processing, wxrks: * Extracts and normalizes each segment's comments text. * Scans that text for valid https:// image links and schedules them for download into the project's reference gallery — see Reference image rules below for what qualifies.

  3. Open the project Overview to confirm the file processed successfully, then access its Translation or Review work unit.

Screenshot of the wxrks project Overview showing the processed json-comments-test-samples.json file, with its Translation work unit row highlighted in a red box.

Step 3: View Comments and Reference Images in the Editor

When a translator or reviewer opens the work unit:

  1. Thumbnail indicator: any segment with a qualifying reference image shows a small thumbnail badge next to its row, so you can spot commented segments while scanning the list.

  2. Click into the segment (select its target field) to activate it. A Comments panel opens directly beneath the source text, showing the full raw comment string exactly as written in the JSON file.

  3. Images carousel: if the comment contains one or more qualifying image URLs, an Images section appears under the comment text with a downloaded preview and 1 / N pagination arrows to page through every reference image attached to that segment.

Screenshot of the wxrks Editor with a segment activated, showing its Comments panel (the raw comment text) and Images carousel (a downloaded reference image with 1/5 pagination), both highlighted in a red box.

  1. Segment context icon: click the information icon on the segment toolbar for the complete context and metadata.

Reference image rules

Not every URL in a comment becomes a visible image. wxrks enforces these rules for security and consistency:

Rule

Specification

Max images per segment

5. Additional URLs in the same comment are ignored.

Protocol

https:// only, default port (443). http:// links are ignored.

Credentials in URL

URLs with embedded credentials (https://user:pass@host/...) are rejected.

Max URL length

2,048 characters.

Supported formats

image/png and image/jpeg, up to 5 MB.

Redirects

Up to 3 redirects are followed; beyond that, the image is skipped.

Host resolution

Must resolve to a public IP address — localhost, loopback, link-local, and private network ranges are all rejected.

If a URL fails any of these checks, wxrks silently skips that image — the comment text itself is still shown.

Step 4: Toggle Segment Comment Visibility

Linguists can hide or show inline comments while translating without changing the project-level setting:

  1. Open the Settings panel in the Editor's right sidebar (gear icon).

  2. Under Your Preferences > Translation Preferences, locate Show Segment Comments.

  3. Check or uncheck it. The preference is saved to your user profile and applies across all documents.

Screenshot of the wxrks Editor Settings sidebar under Your Preferences > Translation Preferences, with the "Show Segment Comments" toggle highlighted in a red box.

ℹ️ Note: Show Segment Comments only appears when the active document is a .json file imported with Show Comments In The Editor enabled. If your role lacks the Edit Visibility Comments permission, the checkbox is visible but disabled.

How Context Sensitive (CS) Translation Uses Comments

When Use Comments In CS is enabled, wxrks passes segment comments to AI models as local guidance, with two safeguards:

  • URL stripping: any https:// image links are removed from the text before it reaches the model, so the AI only sees linguistic instructions.

  • 400-character limit: longer comments are truncated to 400 characters.

Comments never alter global AI agent prompt definitions — they only add context to the specific segment being translated.

Troubleshooting

"Show Segment Comments" is missing from Settings. The toggle only appears when the active document is a .json file imported with Show Comments In The Editor enabled. Re-import the file with that option turned on in its parser Options (or pick a saved filter that has it enabled) — the setting doesn't apply retroactively to files already segmented.

The checkbox is visible but disabled. Your role lacks the Edit Visibility Comments permission. Ask an Account Admin to grant it under People > Users > [User] > Permissions > Editor.

An image URL in my comment isn't showing up. Check it against the reference image rules above — most commonly, the link uses http:// instead of https://, points to a non-image page, or the host isn't publicly reachable.

Quick Reference Summary

Item

Location

Show Comments In The Editor / Use Comments In CS

Upload Files step (project creation or file import) > file's type icon > Options > Flags

Reusable saved filters

Organizational Unit > Project tab > Filter Settings

Show Segment Comments

Editor > Settings (right sidebar) > Your Preferences > Translation Preferences

Required permission

People > Users > [User] > Permissions > Editor > Edit Visibility Comments

Sample test file

docs/uploads/json-comments-test-samples.json

Related Articles
Did this answer your question?