@ti-engine/core 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 This document contains the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.10.0
+
+* feat(localization): `getLabel( label, language, fallback )` takes an optional third argument returned when the key
+  is absent from the loaded catalogue, instead of the `!!! label not found !!!` placeholder. The placeholder is an
+  internal detail and was not exported, so a caller needing this had no option but to hard-code and compare against
+  it — which `@ti-engine/web-framework` and `@ti-engine/competence` both did. The default is unchanged, so a missing
+  label stays loud for every existing call site. This matters because an application configures exactly one labels
+  path (`TI_LOCALIZATION_LABELS_PATH`) — its own — so a *framework*-owned screen resolving its own strings finds
+  nothing in a consumer and needs a literal to degrade to
+* build(release): bump package version from `1.9.1` to `1.10.0`
+
 ## Version 1.9.1
 
 The declarations published in 1.9.0 type-check only for a consumer who has separately configured

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "description": "Microservice framework for Node.js: a Redis-backed message exchange with end-to-end call tracing, retries and tamper-evident message envelopes.",
   "keywords": [
     "microservices",

package/types/utils/localization.d.ts

@@ -1,5 +1,5 @@
 export { localizationLanguageEnum as localizationLanguage };
-export declare var getLabel: (label: string, language?: TiLocalizationLanguage) => string;
+export declare var getLabel: (label: string, language?: TiLocalizationLanguage, fallback?: string) => string;
 export declare var getAllLabels: (language?: TiLocalizationLanguage) => TiLabelsTree;
 export type TiLocalizationLanguage = string;
 /**

package/utils/localization.js

@@ -250,15 +250,22 @@ tools.deepFreeze( labels );
 
 /**
  * Used to return the textual value for a label based on the current system language by default or the specified language code if provided.
+ * <br/>
+ * NOTE: A caller that has a sensible literal to show when the key is absent should pass it as `fallback` rather than
+ * comparing the result against the not-found placeholder. That placeholder is an internal detail, and a caller that
+ * hard-codes it is coupled to a string this module is free to change. This matters most for a framework-owned screen
+ * whose strings live in a catalogue the consuming application does not load — an application configures exactly one
+ * labels path, its own.
  *
  * @method
  * @param {string} label This should be a dot-separated JSON path string.
  * @param {TiLocalizationLanguage} [language] The language code to use for the lookup. If not provided, the current system language will be used.
+ * @param {string} [fallback] Returned when the label is not in the loaded catalogue. Defaults to a visible placeholder.
  * @returns {string}
  * @public
  */
-module.exports.getLabel = ( label, language ) => {
-    return _.get( labels, label + "." + ( ( language ) ? language : config.getSetting( config.setting.LOCALIZATION_LANGUAGE ) ), defaultEmptyLabel );
+module.exports.getLabel = ( label, language, fallback = defaultEmptyLabel ) => {
+    return _.get( labels, label + "." + ( ( language ) ? language : config.getSetting( config.setting.LOCALIZATION_LANGUAGE ) ), fallback );
 };
 
 const labelsCacheByLanguage = new Map();