Skip to content

Docs accuracy and i18n completion from the maintainer review - #144

Merged
dkastl merged 2 commits into
mainfrom
docs/review-cleanup
Aug 5, 2026
Merged

Docs accuracy and i18n completion from the maintainer review#144
dkastl merged 2 commits into
mainfrom
docs/review-cleanup

Conversation

@dkastl

@dkastl dkastl commented Aug 5, 2026

Copy link
Copy Markdown
Member

Final PR from the maintainer review: documentation accuracy and internationalization. Two commits, one per concern.

Docs and helper scripts

  • The three tutorial examples described the pre-v3.0 form: a Broker URL field on the template (connections are admin-managed since Introduce broker connections as reusable configuration #67) and an Insert project boundary link that no longer exists (the Area radio replaced it). Rewritten to the current UI.
  • Both helper shell scripts added the tenant headers exactly when the variables were not set (inverted -z tests), so a tenant-scoped broker never received them. broker_scripts.md also pointed at a scripts/ directory that does not exist and told readers to replace a broker URL "with your actual Redmine API key".
  • init.rb now enforces the redmine_gtt dependency the README always claimed; installing without it broke at runtime anyway, just later and less clearly. README gains a Development section (how to run the Ruby and Vitest suites).
  • Smaller accuracy fixes: the on-demand entity endpoint documents its instance-identifier precondition; release_verification.md no longer claims the callback URL is always built from the request host; a broken sentence, the "Ngix" typo, an http link, a filler paragraph.

i18n

  • Full en/ja/de key parity. 18-19 keys were missing from ja/de entirely, all user-visible: the wizard steps and help texts, the boundary-notes feature including the journal note text (Japanese users received English notes in their issues), and the member/custom-field hints.
  • The Japanese UI is actually Japanese now. A large ja block still carried English values: form labels, publish/copy messages, the threshold hint. Translated.
  • The auth-token hint described a PROXY button removed in Move "connect via proxy" and subscription throttling out of global settings onto connections #95; it now explains what really decides where the token goes (the connection's authentication mode). "Sent from user" becomes "Create issues as" in all three languages, docs included.
  • The copy/publish JS responses used hard-coded English strings; they use the locale now (the command_copied key existed in all three languages, referenced by nothing). The publish/unpublish list icons get the hover hints whose keys also existed unused.
  • Dead keys removed from all three locales, each verified by grep before deletion: the four pre-Redesign the subscription template form with progressive disclosure #66 form section headings, the insert-project-boundary trio, the unused settings-tab key, and the whole gtt_fiware.* namespace of the read API removed in Remove the bespoke NGSI read API #60 (whose status/tracker messages had been swapped in every locale, fittingly for keys nothing read).
  • The list partial stops piping plain values through textilizable, which wiki-rendered user data into <p>-wrapped cells for no benefit.

Verification

YAML validity and full leaf-key parity checked programmatically for all three locales (no missing, no extra keys). Full suite: 355 runs, 1215 assertions, 0 failures; 64 JS tests pass.

Not included, deliberately: moving the two inline <script> blocks into assets, form-prologue helper extraction, and the label for= accessibility pass. Those are real but carry regression risk disproportionate to this PR; follow-up issue to come.

dkastl added 2 commits August 5, 2026 17:57
The tutorial examples described the pre-v3.0 form: a Broker URL field on
the template (connections are admin-managed since #67) and an 'Insert
project boundary' link that no longer exists (the Area radio replaced it).
Both are rewritten to the current UI.

broker_scripts.md pointed at a scripts/ directory that does not exist (the
scripts live in doc/scripts/) and told readers to replace a broker URL
'with your actual Redmine API key'. Both helper scripts added the tenant
headers exactly when the variables were NOT set (inverted -z tests), so a
tenant-scoped broker never received them; -n now.

README gains a Development section (how to run the Ruby and Vitest suites),
and init.rb now enforces the redmine_gtt dependency the README always
claimed: geometry conversion goes through RedmineGtt::Conversions and the
form reads the project boundary, so installing without it broke at runtime
anyway, just later and less clearly.

Smaller accuracy fixes: the on-demand entity endpoint documents its
instance-identifier precondition; release_verification.md no longer claims
the callback URL is always built from the request host (the configured host
name wins since #101); a broken sentence, the Ngix typo, an http link and a
filler closing paragraph.
Every en key now exists in ja and de, genuinely translated (18-19 were
missing entirely: wizard steps and help, boundary notes including the
journal note text that Japanese users received in English, custom-field
and member hints). The large ja block that still carried English values
(form labels, publish/copy messages, threshold hint) is translated.

User-visible fixes across locales:

- The auth-token hint described a PROXY button removed in #95; it now says
  what actually decides where the token is sent (the connection's
  authentication mode).
- 'Sent from user' becomes 'Create issues as' (with ja/de equivalents):
  the old label said nothing about what the member does. Docs follow.
- en subscription_published_error said publishing 'from' the broker;
  en text_alteration_types_ld_info lost the change==update explanation ja
  and de still carried.
- The copy/publish JS responses used hard-coded English; they use the
  locale (the existing command_copied key was defined in all three
  languages and referenced by nothing).
- The publish/unpublish list icons get the hover hints their neighbours
  already had; their keys existed unused.
- The last hard-coded example placeholders move into locale keys.

Dead keys removed from all three locales: the four pre-#66 form section
headings, the insert-project-boundary trio (feature removed), the unused
settings-tab key, and the whole gtt_fiware.* namespace of the read API
removed in #60 (whose status/tracker values had been swapped in every
locale for years, fitting for keys nothing read).

The list partial also stops piping plain values (standard, status, names)
through textilizable, which wiki-rendered user data into wrapped <p> tags
for no benefit.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR finalizes maintainer-review feedback by aligning documentation and helper scripts with the current UI/behavior, and completing internationalization so user-facing strings are consistent across en/ja/de (including wiring previously-unused locale keys into the UI).

Changes:

  • Update docs/tutorial examples and verification notes to match current connection-based UI and host-name/callback behavior.
  • Fix tenant-header handling in helper scripts and correct broker script documentation paths/wording.
  • Enforce the redmine_gtt hard dependency at plugin load time and localize remaining UI/JS strings (copy/publish hints, placeholders), removing unused locale keys.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated no comments.

Show a summary per file
File Description
README.md Adds development test instructions; fixes Redmine plugin docs link to HTTPS.
init.rb Enforces redmine_gtt as a required plugin dependency.
doc/subscription_template.md Updates UI terminology (“Create issues as”) to match current form labels.
doc/scripts/register_all_subscriptions.sh Fixes tenant header inclusion conditions (-n instead of inverted -z).
doc/scripts/delete_all_subscriptions.sh Fixes tenant header inclusion conditions (-n instead of inverted -z).
doc/release_verification.md Corrects callback URL derivation guidance (host name setting vs request host fallback).
doc/issue_emission.md Documents instance-identifier precondition for the on-demand entity endpoint.
doc/index.md Fixes wording/typo (“Nginx”) and replaces filler text with issue-tracker guidance.
doc/examples/temperature_sensor.md Updates example to use admin-managed broker connections and new label text.
doc/examples/location_sensor.md Updates example to use “Area” instead of removed boundary-insert link; new label text.
doc/examples/camera_sensor.md Updates example to use broker connections and new label text.
doc/broker_scripts.md Fixes script paths (doc/scripts) and corrects broker URL / API key wording.
config/locales/ja.yml Completes/cleans up Japanese translations; adds missing keys and removes unused ones.
config/locales/en.yml Removes unused keys; improves/extends strings used by UI/JS placeholders and hints.
config/locales/de.yml Adds missing German keys and updates hints/labels to current UI behavior.
app/views/subscription_templates/publish.js.erb Uses localized error message when broker response lacks Location header.
app/views/subscription_templates/copy.js.erb Localizes copy-to-clipboard success/failure/unavailable notifications.
app/views/subscription_templates/_subscription_template.html.erb Stops textilizable rendering for plain values; adds publish/unpublish hover titles.
app/views/subscription_templates/_form_filters.html.erb Localizes watched-attributes placeholder text.
app/views/subscription_templates/_attachment_row.html.erb Localizes attachment URL/filename placeholders.
app/controllers/subscription_templates_controller.rb Updates comment to match renamed UI label (“Create issues as”).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@dkastl
dkastl merged commit 89607d8 into main Aug 5, 2026
12 checks passed
@dkastl
dkastl deleted the docs/review-cleanup branch August 5, 2026 09:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants