@gram-lang/i18n 1.3.0 → 1.4.1

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
@@ -5,7 +5,7 @@
5
5
 
6
6
  *Part of the [Gram monorepo](https://git.gram-lang.org/gram-lang/gram).*
7
7
 
8
- The translation and normalization module for units and time within the Gram recipe language. It provides high-performance, O(1) lookup dictionaries and normalizers to translate locale-specific aliases (e.g., `càs`, `cuillère à soupe`, `teaspoon`) into standardized canonical representation units (e.g., `tbsp`, `tsp`).
8
+ The translation and normalization module of the Gram recipe language: it normalizes units and time, and holds every word a reader sees, in English and French (the renderer's views and the playground), plus the category labels and the AI language instructions. It provides high-performance, O(1) lookup dictionaries and normalizers to translate locale-specific aliases (e.g., `càs`, `cuillère à soupe`, `teaspoon`) into standardized canonical representation units (e.g., `tbsp`, `tsp`).
9
9
 
10
10
  ---
11
11
 
@@ -42,6 +42,20 @@ console.log(resolveTimeUnit('heures', 'fr')); // 'h'
42
42
  console.log(resolveTimeUnit('minutes')); // 'm'
43
43
  ```
44
44
 
45
+ ### Words and templates
46
+
47
+ `getDictionary(lang)` returns the dictionary of a language (`en` or `fr`): the labels of the renderer's views (`renderer.*`, including the names of the outputs and of the formats), the units of durations (`renderer.durationUnits`, `1h 30min` or `1j 1h`) and the strings of the playground. `fillTemplate(template, values)` fills the `{name}` placeholders of a dictionary string (`"Serve at {time}"` becomes `"Serve at 20:00"`) and leaves a name with no value as written, so a missing value shows up instead of vanishing.
48
+
49
+ ```javascript
50
+ import { getDictionary, fillTemplate } from '@gram-lang/i18n';
51
+
52
+ const t = getDictionary('fr');
53
+ console.log(t.renderer.durationUnits); // { day: 'j', hour: 'h', minute: 'min', second: 's' }
54
+ console.log(fillTemplate('Serve at {time}', { time: '20:00' })); // 'Serve at 20:00'
55
+ ```
56
+
57
+ A key is added in both languages together: a surface never carries a word of its own.
58
+
45
59
  ### ⚙️ How it Works
46
60
 
47
61
  To maintain maximum performance under load (e.g., when compiling/analyzing large numbers of recipes), the dictionaries are compiled once at initialization into flat hash maps using `compileDictionary`. Lookups are `O(1)` operations.
@@ -56,6 +70,10 @@ If a language-specific code (e.g., `'fr'`) is provided, the function checks the
56
70
  * `src/dictionary.ts`: Dictionary compiler helper that transforms structured translations into flat `O(1)` maps.
57
71
  * `src/units.ts`: Mass and volume unit dictionary (French & English) and normalizer.
58
72
  * `src/time.ts`: Time unit dictionary (French & English) and normalizer.
73
+ * `src/locales/`: The `en` and `fr` dictionaries (renderer views, nutrients, playground) and `getDictionary()`.
74
+ * `src/template.ts`: `fillTemplate()`.
75
+ * `src/categories.ts`: Shopping list category keys and their labels per language.
76
+ * `src/ai.ts`: The language instruction added to AI prompts.
59
77
 
60
78
  ---
61
79
 
package/dist/index.d.ts CHANGED
@@ -50,6 +50,64 @@ declare function normalizeUnit(rawUnit: string | undefined | null, lang?: string
50
50
  * return false since their values are already small.
51
51
  */
52
52
  declare function isCoarseUnit(rawUnit: string | undefined | null): boolean;
53
+ /**
54
+ * True for a metric unit of mass (mg, g, kg): a quantity in it is already a
55
+ * weight, so a standardized mass next to it would only say it again. An
56
+ * imperial mass (oz, lb) is not one: its weight in grams still tells something.
57
+ */
58
+ declare function isMetricMassUnit(rawUnit: string | undefined | null, lang?: string): boolean;
59
+ /**
60
+ * A metric mass or volume in kilograms or liters once it reaches 1000 g or
61
+ * 1000 ml (3900 g → 3.9 kg, 2250 ml → 2.25 l), rounded to 2 decimals; any
62
+ * other amount comes back as it was. For what a reader buys (a shopping list)
63
+ * or reads as a total (the weight of a recipe): what is weighed stays in grams,
64
+ * since a scale shows grams and a cook writes "1500 g of flour".
65
+ * Every surface reads a large amount through this, so a shopping list says
66
+ * the same thing in the renderer, `gram shop` and `gram cook`.
67
+ */
68
+ declare function toLargerMetricUnit(value: number, rawUnit: string | undefined | null, lang?: string): {
69
+ value: number;
70
+ unit: string;
71
+ };
72
+ /** True for a unit of mass or volume Gram knows (g, kg, cup, tbsp, c.à.s...). */
73
+ declare function isMeasureUnit(rawUnit: string | undefined | null, lang?: string): boolean;
74
+ /**
75
+ * True when a unit holds a quantity of its own: a number followed by a known
76
+ * unit, glued or not (`about 200g`, `boîte de 400 g`, `8oz tins`). A unit such
77
+ * as `gousse` or `tranche` holds none.
78
+ */
79
+ declare function unitContainsQuantity(rawUnit: string | undefined | null, lang?: string): boolean;
80
+
81
+ /**
82
+ * Numbers as a reader of a language writes them: `1.5` in English, `1,5` in
83
+ * French. Only for what is shown: a number a script or a file reads back (a
84
+ * data attribute, JSON, `.gram` source) keeps its point.
85
+ */
86
+ /**
87
+ * A number in the reader's language, rounded to `maxDecimals` (2 by default),
88
+ * with no thousands separator: `formatNumber(1.5, "fr")` is `"1,5"`,
89
+ * `formatNumber(1500, "fr")` is `"1500"`.
90
+ */
91
+ declare function formatNumber(value: number, lang?: string, maxDecimals?: number): string;
92
+ /** The decimal separator of a language: `"."` in English, `","` in French. */
93
+ declare function decimalSeparator(lang?: string): string;
94
+ /**
95
+ * The decimal points of a quantity already written as text (a range
96
+ * `1.5-2`, a timer `1.5`) in the reader's language: `"1,5-2"` in French.
97
+ * Only a point between two digits changes, so `1/2` or a unit stay as they are.
98
+ */
99
+ declare function localizeDecimals(text: string, lang?: string): string;
100
+ /** `"1/4"` for a value strictly between 0 and 1 that is (nearly) a common fraction. */
101
+ declare function commonFraction(value: number): string | undefined;
102
+ /** True for a unit read in fractions (spoons, cups, imperial measures). */
103
+ declare function isFractionUnit(rawUnit: string | undefined | null, lang?: string): boolean;
104
+ /**
105
+ * A quantity of a spoon, cup or imperial unit as a cook writes it: a whole
106
+ * number and a common fraction (`1.75` cup → `"1 3/4"`, `0.5` tsp → `"1/2"`),
107
+ * or `undefined` when it is not near one (`1.6`), or for any other unit:
108
+ * the caller then writes a decimal.
109
+ */
110
+ declare function toKitchenFraction(value: number, rawUnit: string | undefined | null, lang?: string): string | undefined;
53
111
 
54
112
  declare function getAiLanguageInstruction(lang?: string): string;
55
113
 
@@ -74,18 +132,162 @@ declare function getDefaultCategories(lang?: string): string[];
74
132
 
75
133
  declare const en: {
76
134
  renderer: {
135
+ viewsPaused: string;
136
+ viewsPausedDescription: string;
137
+ /** What a surface offers next to paused views: jump to the error. */
138
+ showError: string;
139
+ /** An output the recipe has nothing for (a run sheet with nothing to schedule). */
140
+ outputEmpty: string;
141
+ /** The serving time controls of a view laid out in time (the editor's panel). */
142
+ serving: {
143
+ label: string;
144
+ clear: string;
145
+ clearTitle: string;
146
+ suggest: string;
147
+ none: string;
148
+ whyNot: string;
149
+ earliest: string;
150
+ };
151
+ /** The session controls of a view (the editor's panel): scale, baker's reference, stock. */
152
+ session: {
153
+ title: string;
154
+ scale: string;
155
+ portions: string;
156
+ byIngredient: string;
157
+ ingredient: string;
158
+ qty: string;
159
+ unit: string;
160
+ apply: string;
161
+ bakersReference: string;
162
+ auto: string;
163
+ stock: string;
164
+ stockHint: string;
165
+ reset: string;
166
+ scaled: string;
167
+ inStock: string;
168
+ scaleError: string;
169
+ };
170
+ /** The name of each output of the renderer (`outputs`), by its id. */
171
+ outputs: Record<string, string>;
172
+ /** The name of each format a view can be written in (`FORMATS`). */
173
+ formats: Record<string, string>;
77
174
  shoppingList: string;
175
+ /** The ingredients a section uses, above its steps. */
176
+ ingredients: string;
177
+ instructions: string;
178
+ /** The comments at the end of a line, gathered under the recipe. */
179
+ notes: string;
180
+ /** Between the options of an alternative (`@butter|oil`). */
181
+ or: string;
182
+ /** The head of the metadata block of the Markdown recipe. */
183
+ metadata: string;
184
+ /** Marks a composite ingredient (`@yolk<@egg`) in a list. */
185
+ composite: string;
186
+ /** Under a composite in the shopping list, the share of the item used whole (`@egg{1}` next to `@yolk<@egg`). */
187
+ directUse: string;
188
+ /** The label of the total mass in the recipe's header. */
189
+ totalMass: string;
190
+ incomplete: string;
191
+ /** After a timer that is a passive wait, and the short mark of an alternative. */
192
+ passive: string;
193
+ alt: string;
194
+ unknownIngredient: string;
195
+ unknownReference: string;
196
+ /** The portions of the recipe (`portions:`), and once it is scaled. */
197
+ servings: string;
198
+ servingsScaled: string;
199
+ /** The word after the portions stepper, by plural category (`Intl.PluralRules`). */
200
+ portionsUnit: {
201
+ one: string;
202
+ other: string;
203
+ };
204
+ /** The badge of a scaled recipe in the hero bar ("×1.5"). */
205
+ scaledRecipe: string;
206
+ /** The pencil button beside the portions, where the surface can change them. */
207
+ changePortions: string;
78
208
  cookware: string;
79
209
  equipment: string;
80
210
  nutrition: string;
211
+ /** The units of a computed duration (`formatDuration`): "1d 2h", "1h 30min", "45s". */
212
+ durationUnits: {
213
+ day: string;
214
+ hour: string;
215
+ minute: string;
216
+ second: string;
217
+ };
81
218
  totalTime: string;
82
219
  idleTime: string;
83
220
  activeTime: string;
84
221
  prepTime: string;
85
222
  totalTimeTooltip: string;
86
- idleTimeTooltip: string;
223
+ /** Under the total time's breakdown: where the hour-by-hour plan lives. */
224
+ totalTimeRunSheetHint: string;
87
225
  activeTimeCardTooltip: string;
88
226
  prepTimeTooltip: string;
227
+ miseEnPlace: string;
228
+ scheduleLabel: string;
229
+ restsLabel: string;
230
+ restsShortest: string;
231
+ restsBalanced: string;
232
+ restsLongest: string;
233
+ schedulePerSection: string;
234
+ scheduleUpfront: string;
235
+ schedulePerDay: string;
236
+ dayBefore: string;
237
+ dayToday: string;
238
+ runSheetStep: string;
239
+ runSheetRest: string;
240
+ runSheetUnnamedSection: string;
241
+ runSheetProblems: string;
242
+ runSheetOutside: string;
243
+ runSheetExceeds: string;
244
+ runSheetDayMismatch: string;
245
+ runSheetPast: string;
246
+ runSheetMulti: string;
247
+ runSheetTitle: string;
248
+ runSheetFor: string;
249
+ runSheetDays: string;
250
+ runSheetDaysMany: string;
251
+ runSheetVisits: string;
252
+ runSheetVisitsMany: string;
253
+ runSheetWork: string;
254
+ runSheetServe: string;
255
+ runSheetAbout: string;
256
+ runSheetKit: string;
257
+ runSheetLegendCook: string;
258
+ runSheetLegendThread: string;
259
+ runSheetProgram: string;
260
+ runSheetExecution: string;
261
+ runSheetIngredients: string;
262
+ runSheetStart: string;
263
+ runSheetContinued: string;
264
+ runSheetLeaving: string;
265
+ runSheetMadeOn: string;
266
+ runSheetMadeAt: string;
267
+ runSheetMadeEarlier: string;
268
+ runSheetInStock: string;
269
+ runSheetProgramStep: string;
270
+ runSheetProgramSteps: string;
271
+ runSheetRange: string;
272
+ runSheetPossibleFrom: string;
273
+ runSheetFixedService: string;
274
+ runSheetFixedVisit: string;
275
+ runSheetNextVisit: string;
276
+ runSheetNextVisitSameDay: string;
277
+ runSheetServeAt: string;
278
+ runSheetStretchedTo: string;
279
+ runSheetShortenedTo: string;
280
+ runSheetUntilClock: string;
281
+ runSheetNothing: string;
282
+ runSheetFindOk: string;
283
+ runSheetFindRejected: string;
284
+ runSheetFindStart: string;
285
+ runSheetFindNone: string;
286
+ runSheetAdjusted: string;
287
+ runSheetAdjustedMany: string;
288
+ runSheetNoAdjustment: string;
289
+ runSheetEarliest: string;
290
+ runSheetEarliestNone: string;
89
291
  est: string;
90
292
  passiveTimeTooltip: string;
91
293
  activeTimeTooltip: string;
@@ -105,9 +307,14 @@ declare const en: {
105
307
  breakdownPassive: string;
106
308
  breakdownTimer: string;
107
309
  breakdownPrep: string;
310
+ colon: string;
108
311
  standardizedMass: string;
109
312
  quantity: string;
110
313
  intermediateIngredient: string;
314
+ tooltipMass: string;
315
+ tooltipPreparation: string;
316
+ tooltipBakers: string;
317
+ tooltipTakenFrom: string;
111
318
  alternatives: string;
112
319
  decreasePortions: string;
113
320
  editPortions: string;
@@ -115,6 +322,9 @@ declare const en: {
115
322
  returnToStep: string;
116
323
  mixedUnitsTooltip: string;
117
324
  mixedUnits: string;
325
+ copyShoppingList: string;
326
+ copied: string;
327
+ toggleStepDone: string;
118
328
  purchasingWeight: string;
119
329
  gross: string;
120
330
  intermediateResult: string;
@@ -122,12 +332,29 @@ declare const en: {
122
332
  estimatedSuffix: string;
123
333
  missingMass: string;
124
334
  someIngredients: string;
335
+ massTitle: string;
336
+ massSectionTitle: string;
337
+ massEstimated: string;
338
+ massEstimatedDetail: string;
339
+ massIncomplete: string;
340
+ massIncompleteDetail: string;
341
+ massMethodDensity: string;
342
+ massMethodUnitWeight: string;
343
+ massIncompleteHint: string;
125
344
  nutritionWholeRecipe: string;
126
345
  nutritionPerPortion: string;
127
346
  nutritionPer100g: string;
128
347
  nutritionRawMassNote: string;
129
348
  nutritionRawMassNotePartial: string;
130
349
  incompleteData: string;
350
+ /** Under the nutrition of the text format when a mass was estimated from a density. */
351
+ nutritionEstimated: string;
352
+ nutritionSalt: string;
353
+ nutritionTableTitle: string;
354
+ nutritionReferenceIntake: string;
355
+ nutritionReferenceIntakeNote: string;
356
+ nutritionNutrient: string;
357
+ nutritionWholeRecipeTotal: string;
131
358
  ofWhich: string;
132
359
  nutrients: {
133
360
  calories: string;
@@ -149,9 +376,42 @@ declare const en: {
149
376
  writePlaceholder: string;
150
377
  outputTab: string;
151
378
  viewLabel: string;
379
+ formatLabel: string;
152
380
  loadExample: string;
153
381
  recipe: string;
154
- scaleFactor: string;
382
+ studioTitle: string;
383
+ settingsButton: string;
384
+ settingsHint: {
385
+ text: string;
386
+ dismiss: string;
387
+ };
388
+ activeOptionsBadge: string;
389
+ resetAll: string;
390
+ resetSection: string;
391
+ openScheduleSettings: string;
392
+ scheduleButton: string;
393
+ sections: {
394
+ schedule: string;
395
+ scale: string;
396
+ bakersMath: string;
397
+ display: string;
398
+ physics: string;
399
+ stock: string;
400
+ };
401
+ badges: {
402
+ default: string;
403
+ active: string;
404
+ inactive: string;
405
+ standardized: string;
406
+ nutritionActive: string;
407
+ byIngredient: string;
408
+ inStock: string;
409
+ serveAt: string;
410
+ customHours: string;
411
+ };
412
+ a11y: {
413
+ closeDrawer: string;
414
+ };
155
415
  examples: {
156
416
  newRecipe: string;
157
417
  canneles: string;
@@ -163,7 +423,24 @@ declare const en: {
163
423
  jsonTree: string;
164
424
  markdown: string;
165
425
  preview: string;
166
- gantt: string;
426
+ runSheet: string;
427
+ serveWhenTitle: string;
428
+ serveWhenNone: string;
429
+ serveWhenWhyNot: string;
430
+ earliestTitle: string;
431
+ earliestNone: string;
432
+ earliestUse: string;
433
+ planSummary: string;
434
+ planServeAt: string;
435
+ planTimeZone: string;
436
+ planAvailability: string;
437
+ planSpecificHours: string;
438
+ planDayUnavailable: string;
439
+ serveAtClear: string;
440
+ serveAtClearTitle: string;
441
+ serveOtherSlots: string;
442
+ planClear: string;
443
+ planInvalid: string;
167
444
  gantt_active: string;
168
445
  gantt_passive: string;
169
446
  gantt_compact: string;
@@ -183,6 +460,7 @@ declare const en: {
183
460
  };
184
461
  options: {
185
462
  scaleTitle: string;
463
+ scalePortions: string;
186
464
  scaleGlobal: string;
187
465
  scaleByIngredient: string;
188
466
  selectIngredient: string;
@@ -193,6 +471,13 @@ declare const en: {
193
471
  enableBakersMath: string;
194
472
  bakersMathDesc: string;
195
473
  hideAbsolute: string;
474
+ showComments: string;
475
+ commentsDesc: string;
476
+ showStepQuantities: string;
477
+ stepQuantitiesDesc: string;
478
+ nutritionBasis: string;
479
+ nutritionBasisAuto: string;
480
+ rejectedSlots: string;
196
481
  forceReference: string;
197
482
  autoDetect: string;
198
483
  physicalAnalysis: string;
@@ -203,8 +488,38 @@ declare const en: {
203
488
  stockTitle: string;
204
489
  stockDesc: string;
205
490
  };
491
+ help: {
492
+ schedule: string;
493
+ rests: string;
494
+ serveAt: string;
495
+ serveSuggestions: string;
496
+ timeZone: string;
497
+ availability: string;
498
+ scalePortions: string;
499
+ scaleGlobal: string;
500
+ scaleByIngredient: string;
501
+ bakersMath: string;
502
+ comments: string;
503
+ stepQuantities: string;
504
+ nutritionBasis: string;
505
+ bakersMathOnly: string;
506
+ bakersReference: string;
507
+ massStandardization: string;
508
+ yieldManagement: string;
509
+ nutrition: string;
510
+ /** The note of the "Schedule & Service" section: what these settings change in each view. */
511
+ scheduleNote: string;
512
+ scheduleNoteLink: string;
513
+ physicsDisclaimer: string;
514
+ stockItem: string;
515
+ };
206
516
  output: {
207
517
  copy: string;
518
+ print: string;
519
+ /** The tabs of the views of the recipe. */
520
+ views: string;
521
+ /** The tab of the inspectors (AST, JSON), apart from the views. */
522
+ inspect: string;
208
523
  loading: string;
209
524
  };
210
525
  warnings: {
@@ -240,6 +555,8 @@ declare const en: {
240
555
  editor: string;
241
556
  preview: string;
242
557
  };
558
+ fullscreen: string;
559
+ exitFullscreen: string;
243
560
  analysisOptions: string;
244
561
  analysis: string;
245
562
  massNorm: string;
@@ -254,4 +571,11 @@ type GramLocale = typeof en;
254
571
 
255
572
  declare function getDictionary(lang?: string): GramLocale;
256
573
 
257
- export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type GramLocale, type LanguageDict, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, type UnitMap, compileDictionary, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, isCategoryKey, isCoarseUnit, normalizeUnit, resolveTimeUnit, unitKey };
574
+ /**
575
+ * A dictionary string with each `{name}` replaced from `values`
576
+ * ("Serve at {time}" → "Serve at 20:00"). A name with no value is left as
577
+ * written, so a missing value shows up instead of vanishing.
578
+ */
579
+ declare function fillTemplate(template: string, values: Readonly<Record<string, string>>): string;
580
+
581
+ export { CATEGORY_KEYS, type CategoryKey, type CompiledDict, type GramLocale, type LanguageDict, TIME_BY_LANG, TIME_DICTIONARIES, TIME_GLOBAL, TIME_TO_MINUTES, UNIT_BY_LANG, UNIT_CONVERSIONS, UNIT_DICTIONARIES, UNIT_GLOBAL, type UnitMap, commonFraction, compileDictionary, decimalSeparator, fillTemplate, formatNumber, getAiLanguageInstruction, getCategoryLabels, getDefaultCategories, getDictionary, isCategoryKey, isCoarseUnit, isFractionUnit, isMeasureUnit, isMetricMassUnit, localizeDecimals, normalizeUnit, resolveTimeUnit, toKitchenFraction, toLargerMetricUnit, unitContainsQuantity, unitKey };