Clarify ambiguous Analytics strings for translators

AGENTS.md

@@ -19,6 +19,8 @@ This `AGENTS.md` file provides guidelines for OpenAI Codex and other AI agents i
 
 Agents should focus on the core application logic and ignore files or folders marked as third-party, sample, or media-related. All changes should preserve the integrity of external dependencies and translations.
 
+For single-word or otherwise ambiguous translatable strings, add a `// TRANSLATORS:` comment immediately before the translation call when context is needed. Explain the intended meaning, whether the word is a noun or a verb, and its UI context where helpful (for example, “Aggregate” is a verb). Keep hints brief and factual, and put each translation call on its own line so its comment applies to the correct string.
+
 All new user-interface elements must reuse the app's existing templates and shared CSS classes. Before adding custom markup or styling, find the corresponding control or dialog pattern in `templates/` and apply it consistently; extend the shared pattern when no suitable template exists instead of introducing an unstyled native control or a one-off design.
 
 For every user-facing change, add a meaningful one-liner to the corresponding section (Added, Changed, Fixed) in CHANGELOG.md. Technical fixes that do not change user-facing behavior, such as correcting a migration's Doctrine type argument, do not require a changelog entry. Add only one changelog entry per feature or fix: when work on the same change is iterated within a chat, update the existing entry as needed instead of adding another line. Do not add entries to a closed milestone which has a data. if no open milestone exists, add a new section to the changelog.

CHANGELOG.md

@@ -7,6 +7,7 @@
 - OCS endpoints to list accessible reports and owned datasets, retrieve report metadata and filtered data including shared reports, and add or delete dataset rows.
 
 ### Changed
+- Clarify ambiguous report actions, chart and data terminology, and placeholders with translator comments.
 - Simplify folder navigation and icons, using the URL to select content and keeping Overview groups collapsed.
 
 ### Fixed

js/app.js

@@ -758,6 +758,7 @@ Object.assign(OCA.Analytics.Datasource = {
 
         OCA.Analytics.Notification.htmlDialogUpdate(
             editor,
+            // TRANSLATORS: {linkstart} and {linkend} wrap the documentation link. Preserve the text-variable syntax and any <br> tags in this guidance.
             t('analytics', 'Keep the selected path and replace parts of the file name with text variables, for example report_%today%(Y-m-d).csv. The variable is resolved when the data load runs. See the {linkstart}Wiki{linkend}.')
                 .replace('{linkstart}', '<a href="https://github.com/Rello/analytics/wiki/Filter,-chart-options-&-drilldown#text-variables" target="_blank" rel="noreferrer noopener">')
                 .replace('{linkend}', '</a>')
@@ -1139,6 +1140,7 @@ Object.assign(OCA.Analytics.Datasource = {
 
         OCA.Analytics.Notification.htmlDialogUpdate(
             content,
+            // TRANSLATORS: {linkstart} and {linkend} wrap the documentation link. Preserve the text-variable syntax and any <br> tags in this guidance.
             t('analytics', 'Select the required columns.<br>Rearrange the sequence with drag & drop.<br>Remove all selections to reset.<br>Add custom columns including text variables for dates. See the {linkstart}Wiki{linkend}.')
                 .replace('{linkstart}', '<a href="https://github.com/Rello/analytics/wiki/Filter,-chart-options-&-drilldown#text-variables" target="_blank">')
                 .replace('{linkend}', '</a>')
@@ -1267,6 +1269,7 @@ Object.assign(OCA.Analytics.Share = {
         let navigationItem = evt.target.closest('div');
 
         OCA.Analytics.Notification.htmlDialogInitiate(
+            // TRANSLATORS: Verb: give other people access to this report, dataset, or panorama.
             t('analytics', 'Share') + ' ' + navigationItem.dataset.name,
             OCA.Analytics.Notification.dialogClose
         );
@@ -1336,6 +1339,7 @@ Object.assign(OCA.Analytics.Share = {
 
         linkRow.getElementById('row').dataset.id = id;
         if (add) linkRow.getElementById('shareLinkTitle').innerText = t('analytics', 'Add share link');
+        // TRANSLATORS: Noun: a public link that gives access to the shared item.
         else linkRow.getElementById('shareLinkTitle').innerText = t('analytics', 'Share link');
 
         if (add) {
@@ -1801,6 +1805,7 @@ Object.assign(OCA.Analytics.Threshold = {
 
         if (data.option === 'new') { // adjust the text for the "new records" option
             data.value = '';
+            // TRANSLATORS: Noun: a newly added data row; also used as a notification subject.
             data.dimension1 = t('analytics', 'new record');
             data.option = '';
         }

js/dataset.js

@@ -735,7 +735,9 @@ Object.assign(OCA.Analytics.Dataset.Dataset = {
 
         const role = document.createElement('select');
         role.className = 'sidebarInput flexibleColumnRole';
+        // TRANSLATORS: Noun: a data column used to identify or group records, such as region or date.
         role.add(new Option(t('analytics', 'Dimension'), 'dimension'));
+        // TRANSLATORS: Noun: a numeric data column that can be aggregated, such as revenue.
         role.add(new Option(t('analytics', 'Measure'), 'measure'));
         role.value = column.role || 'dimension';
 
@@ -744,6 +746,7 @@ Object.assign(OCA.Analytics.Dataset.Dataset = {
         nullable.type = 'checkbox';
         nullable.className = 'flexibleColumnNullable';
         nullable.checked = column.nullable === true;
+        // TRANSLATORS: Column setting: allow missing values in this numeric field.
         nullableLabel.append(nullable, document.createTextNode(' ' + t('analytics', 'Nullable')));
 
         const aggregation = document.createElement('select');