roleplay-data 0.2.0 → 0.3.0

package/README.md

@@ -85,6 +85,33 @@ Règles des thèmes :
 
 ---
 
+## 📏 Unités (i18n des mesures)
+
+Les données embarquent des **unités canoniques métriques** (SI) — la conversion
+vers les systèmes locaux (lb/oz…) se fait **à l'affichage**, pas dans les données :
+
+| Champ | Unité canonique | Helper d'affichage |
+|---|---|---|
+| `item.weight` | grammes | `formatItemWeight(weight, locale)` |
+| `vehicle.massKg` | kg | `formatVehicleMass(massKg, locale)` |
+| `vehicle.fuelCapacity` | litres | à convertir par le consommateur |
+| `vehicle.maxSpeed` | km/h | à convertir par le consommateur |
+| `cargo.maxWeightKg` | kg | à convertir par le consommateur |
+
+```js
+import { formatItemWeight, formatVehicleMass } from 'roleplay-data';
+
+formatItemWeight(950, 'fr');            // "950 g"     (métrique)
+formatItemWeight(950, 'en');            // "2 lb 2 oz" (impérial)
+formatItemWeight(950, 'en', { unit: 'metric' }); // "950 g" (forcé)
+formatVehicleMass(1480, 'en');          // "3 263 lb"
+```
+
+Le système retenu dérive de la locale (métrique pour fr/es/de/…, impérial pour
+en/us…) — il peut être **forcé** via `opts.unit`.
+
+---
+
 ## Consumption
 
 ### npm

package/catalog/schemas/item.schema.json

@@ -51,7 +51,7 @@
         "weight": {
           "type": "number",
           "minimum": 0,
-          "description": "Poids en grammes."
+          "description": "Poids en grammes (unité canonique métrique). Convertir à l'affichage selon la locale (lb/oz…) via formatItemWeight."
         },
         "food": {
           "type": "number",

package/catalog/schemas/vehicle.schema.json

@@ -58,17 +58,17 @@
         "massKg": {
           "type": "number",
           "minimum": 0,
-          "description": "Masse du véhicule en kg."
+          "description": "Masse en kg (unité canonique métrique). Convertir à l'affichage selon la locale (lb…) via formatVehicleMass."
         },
         "fuelCapacity": {
           "type": "number",
           "minimum": 0,
-          "description": "Capacité du réservoir (unité projet)."
+          "description": "Capacité du réservoir en litres (canonique SI)."
         },
         "maxSpeed": {
           "type": "number",
           "minimum": 0,
-          "description": "Vitesse maximale (unité projet)."
+          "description": "Vitesse maximale en km/h (canonique SI)."
         },
         "cargo": {
           "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roleplay-data",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Base de données RP open source : items, véhicules, thèmes (images + renommages) et i18n (fr/en requis). Source de vérité unique, consommable en package npm, seed SQL/MongoDB ou archive d'assets.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -27,6 +27,9 @@ export {
   itemLocalizedName,
   itemLocalizedDescription,
   vehicleLocalizedName,
+  unitsForLocale,
+  formatItemWeight,
+  formatVehicleMass,
 } from './localize.js';
 
 const here = dirname(fileURLToPath(import.meta.url));

package/src/localize.d.ts

@@ -28,4 +28,17 @@ export function itemLocalizedDescription(
 export function vehicleLocalizedName(
   vehicle: { brand?: LocalizedLike; model?: LocalizedLike } | null | undefined,
   locale?: string
-): string;
+): string;
+
+export type UnitSystem = 'metric' | 'imperial';
+
+export type UnitOptions = { unit?: UnitSystem };
+
+/** Résout le système d'unités pour une locale (métrique par défaut). */
+export function unitsForLocale(locale?: string, opts?: UnitOptions): UnitSystem;
+
+/** Formate un poids d'item (grammes, canonique) selon la locale : g/kg ou lb/oz. */
+export function formatItemWeight(grams: number, locale?: string, opts?: UnitOptions): string;
+
+/** Formate une masse de véhicule (kg, canonique) selon la locale : kg ou lb. */
+export function formatVehicleMass(kg: number, locale?: string, opts?: UnitOptions): string;

package/src/localize.js

@@ -25,4 +25,59 @@ export function vehicleLocalizedName(vehicle, locale) {
   const brand = localize(vehicle.brand, locale);
   const model = localize(vehicle.model, locale);
   return `${brand} ${model}`.trim();
+}
+
+/* ------------------------------------------------------------------ *
+ * Unités (i18n des mesures) — données canoniques en métrique (SI),
+ * conversion à l'affichage selon la locale. Le consommateur peut imposer
+ * un système via opts.unit.
+ * ------------------------------------------------------------------ */
+
+/** Locales dont le système usuel de masse est le métrique. */
+const METRIC_LOCALES = new Set([
+  'fr', 'es', 'it', 'de', 'pt', 'nl', 'pl', 'ru', 'tr', 'ar', 'cs', 'hu', 'ro', 'sv', 'fi',
+]);
+
+/** Résout le système d'unités pour une locale (métrique par défaut). */
+export function unitsForLocale(locale, opts = {}) {
+  if (opts.unit === 'metric' || opts.unit === 'imperial') return opts.unit;
+  const key = (locale || 'en').toLowerCase().slice(0, 2);
+  return METRIC_LOCALES.has(key) ? 'metric' : 'imperial';
+}
+
+function fmt(n) {
+  if (!Number.isFinite(n)) return '0';
+  return n.toLocaleString('fr-FR', { maximumFractionDigits: 1 });
+}
+
+const GRAMS_PER_LB = 453.59237;
+const GRAMS_PER_OZ = 28.349523;
+
+/**
+ * Formate un poids d'item (en grammes, canonique) selon la locale :
+ * métrique → « 950 g » / « 1,5 kg » ; impérial → « 2 lb » / « 1 lb 8 oz ».
+ */
+export function formatItemWeight(grams, locale, opts = {}) {
+  const g = Number(grams) || 0;
+  if (unitsForLocale(locale, opts) === 'imperial') {
+    const lb = g / GRAMS_PER_LB;
+    if (lb < 1) return `${fmt(g / GRAMS_PER_OZ)} oz`;
+    const wholeLb = Math.floor(lb);
+    const oz = Math.round((lb - wholeLb) * 16);
+    if (oz >= 16) return `${fmt(wholeLb + 1)} lb`;
+    return oz === 0 ? `${fmt(wholeLb)} lb` : `${fmt(wholeLb)} lb ${oz} oz`;
+  }
+  return g < 1000 ? `${fmt(g)} g` : `${fmt(g / 1000)} kg`;
+}
+
+/**
+ * Formate une masse de véhicule (kg, canonique) selon la locale :
+ * métrique → « 1 480 kg » ; impérial → « 3 263 lb ».
+ */
+export function formatVehicleMass(kg, locale, opts = {}) {
+  const k = Number(kg) || 0;
+  if (unitsForLocale(locale, opts) === 'imperial') {
+    return `${fmt(k * 2.2046226)} lb`;
+  }
+  return `${fmt(k)} kg`;
 }