@numericoach/gskills-admin-cli 0.1.16 → 0.1.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,8 +51,13 @@ Use the listed `cache.scopes` with `gskills-admin cache invalidate` after create
51
51
 
52
52
  AI translation is available for content that has native AI translation in the editor:
53
53
 
54
+ Warning: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
55
+
56
+ For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed text while preserving non-text target block data:
57
+
54
58
  ```bash
55
59
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
60
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
56
61
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
57
62
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
58
63
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -1294,7 +1294,8 @@ var runTranslateCommand = async (kind, id, ctx) => {
1294
1294
  if (!hasFlag(ctx, "yes") && !hasFlag(ctx, "dry-run")) {
1295
1295
  throw new CliError("AI translation writes content. Add --yes or use --dry-run.", 2);
1296
1296
  }
1297
- return requestApi(`/api/cli/translate/${kind}`, {
1297
+ const mode = getStringFlag(ctx, "mode") ?? "upsert";
1298
+ const result = await requestApi(`/api/cli/translate/${kind}`, {
1298
1299
  method: "POST",
1299
1300
  body: JSON.stringify({
1300
1301
  id,
@@ -1305,10 +1306,12 @@ var runTranslateCommand = async (kind, id, ctx) => {
1305
1306
  take: getNumberFlag(ctx, "take"),
1306
1307
  targetLanguages,
1307
1308
  sourceLanguage: getStringFlag(ctx, "from") ?? getStringFlag(ctx, "source-language"),
1308
- mode: getStringFlag(ctx, "mode") ?? "upsert",
1309
+ sourceHistoryEntryId: getStringFlag(ctx, "source-history") ?? getStringFlag(ctx, "source-history-entry"),
1310
+ mode,
1309
1311
  dryRun: hasFlag(ctx, "dry-run")
1310
1312
  })
1311
1313
  });
1314
+ return addTranslatePagesWarning(kind, mode, result);
1312
1315
  };
1313
1316
  var syncLogs = (ctx) => {
1314
1317
  const searchParams = new URLSearchParams;
@@ -1583,7 +1586,7 @@ var schemaHelp = () => ({
1583
1586
  { name: "sync presets", writes: false },
1584
1587
  { name: "cache scopes", writes: false },
1585
1588
  { name: "cache invalidate", required: ["--instance"], flags: ["--scope", "--languages", "--yes", "--dry-run"], writes: true },
1586
- { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--yes", "--dry-run"], writes: true },
1589
+ { name: "translate", args: ["kind", "id?"], required: ["--to"], flags: ["--ids", "--all", "--instance", "--from", "--where", "--take", "--mode", "--source-history", "--yes", "--dry-run"], writes: true },
1587
1590
  { name: "feedback claim", args: ["feedbackId"], flags: ["--dry-run"], writes: true },
1588
1591
  { name: "feedback send-claim", args: ["feedbackId"], flags: ["--recipient-email", "--recipient-name", "--cc", "--subject", "--body", "--yes", "--dry-run"], writes: true },
1589
1592
  { name: "feedback send-reply", args: ["feedbackId"], flags: ["--subject", "--subject-file", "--body-file", "--translated-subject", "--translated-subject-file", "--translated-body-file", "--user-language", "--current-language", "--yes", "--dry-run"], writes: true },
@@ -1690,10 +1693,25 @@ var translateHelp = () => ({
1690
1693
  "learning-paths",
1691
1694
  "chromebook-exercises"
1692
1695
  ],
1693
- modes: ["upsert", "create", "update"],
1696
+ modes: ["upsert", "create", "update", "patch"],
1694
1697
  selection: "Pass one id, --ids for several source rows, or --all with optional --instance, --from, --where and --take.",
1698
+ warning: PAGE_TRANSLATION_REWRITE_WARNING,
1699
+ patchMode: "For pages, --mode patch uses source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.",
1695
1700
  note: "Uses the same AI translation helpers as the editors. Dry-run plans the write without calling AI."
1696
1701
  });
1702
+ var PAGE_TRANSLATION_REWRITE_WARNING = "WARNING: translate pages is a full translated-page rewrite, not a diff update. Rebuilding target pages can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.";
1703
+ var addTranslatePagesWarning = (kind, mode, result) => {
1704
+ if (kind !== "pages" && kind !== "page")
1705
+ return result;
1706
+ if (mode !== "update" && mode !== "upsert")
1707
+ return result;
1708
+ if (!result || typeof result !== "object" || Array.isArray(result))
1709
+ return result;
1710
+ return {
1711
+ ...result,
1712
+ warning: PAGE_TRANSLATION_REWRITE_WARNING
1713
+ };
1714
+ };
1697
1715
  var feedbackHelp = () => ({
1698
1716
  usage: [
1699
1717
  "gskills-admin feedback send-reply <feedbackId> --subject 'GSkills - ...' --body-file ./reply.fr.txt --dry-run",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@numericoach/gskills-admin-cli",
3
- "version": "0.1.16",
3
+ "version": "0.1.17",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Admin-only CLI for GSkills super-admin operations.",
@@ -166,6 +166,7 @@ Selection can be one source row, several source rows, or all matching rows:
166
166
 
167
167
  ```bash
168
168
  gskills-admin translate pages <pageId> --to en,es --dry-run --output json
169
+ gskills-admin translate pages <pageId> --from fr --to en,es --mode patch --dry-run --output json
169
170
  gskills-admin translate pages --ids <pageId,pageId> --from fr --to en --dry-run --output json
170
171
  gskills-admin translate pages --all --instance global --from fr --to en --take 100 --dry-run --output json
171
172
  gskills-admin translate quizzes <quizId> --to en --yes --output json
@@ -174,8 +175,24 @@ gskills-admin translate knowledge-video <knowledgeId> --from en --to es --yes --
174
175
 
175
176
  Always dry-run first. Dry-run lists planned rows and target languages without calling AI or writing data. Real runs require `--yes`.
176
177
 
178
+ Warning for pages: `translate pages` rewrites each translated page from the source page. It is not a diff update. Recreating translated pages this way can lose activity-specific fields, quiz ids, embedded ids, or future custom block data if the translator does not preserve them. Prefer the app diff update flow for pages with activities or custom blocks.
179
+
180
+ For pages with activities or custom blocks, prefer `--mode patch`. It uses the source page history to update changed translatable text while preserving target non-text block data such as activity ids, quiz ids, embedded ids, files, and future custom fields. It updates existing translations only and fails when no previous source history exists.
181
+
177
182
  For quizzes, the CLI mirrors the quiz thematic through `categoryId` across translations.
178
183
 
184
+ Everything translated by the CLI and stored in the DB works as a family. A page is still one page, even when the DB stores one row per language. Do not tell a non-technical user that one page became 40 pages, unless they explicitly ask for DB-level detail.
185
+
186
+ When a translated thing has relations, translate or relink those relations too. A translated page, quiz, badge, resource, knowledge item, menu entry, or learning path should not quietly point back to the French-only relation when a same-language relation exists.
187
+
188
+ For learning paths, a complete translation includes the parcours itself, its groups, its items, same-language page, quiz, resource, and knowledge references when available, the awarded badge family, and each translated parcours linked to the badge in the same language. This exact trap has happened: the parcours translated correctly but every translated parcours still pointed to the French badge.
189
+
190
+ When explaining CLI work to the user, use `gskills-vocabulary`. Speak like a GSkills admin or end user, not like a database. Use words like page, quiz, parcours, badge, menu, resource, and knowledge base. Do not lead with ids, row counts, parent ids, or schema terms unless the user asks for them.
191
+
192
+ Users could do most of these content tasks in the GSkills UI. The reason they ask Codex is speed. Keep the answer simple: what changed, what stays hidden or visible, and what was verified.
193
+
194
+ After translating content, query the DB or CLI output to prove there are no missing languages, no unexpected active content, no missing related content, and no language mismatch between connected things.
195
+
179
196
  For internal knowledge videos, use `knowledge-video`. It queues the same native video localization workflow as the editor, so it creates a localization job instead of copying the original media.
180
197
 
181
198
  After visible content translation, read the cache hint in the response and invalidate the narrow scope before checking the deploy UI.