@sveltekit-i18n/base 3.0.0-next.3 → 3.0.0

package/README.md

@@ -66,7 +66,7 @@ import parser from '@sveltekit-i18n/parser-curly';
 
 /** @type {import('@sveltekit-i18n/base').Config.T} */
 const config = {
-  parser: parser({ /* parser options */ }),
+  parser: parser({ onReport: null, /* other parser options */ }),
   loaders: [
     {
       locale: 'en',
@@ -134,7 +134,7 @@ import i18n from '@sveltekit-i18n/base';
 import parser from '@sveltekit-i18n/parser-icu';
 
 const config = {
-  parser: parser(),
+  parser: parser({ onReport: null }),
   loaders: [/* ... */],
 };
 ```
@@ -363,7 +363,7 @@ import parser from '@sveltekit-i18n/parser-curly';
 type Params = [payload?: Record<string, unknown>];
 
 const config: Config.T<Params> = {
-  parser: parser(),
+  parser: parser({ onReport: null }),
   loaders: [/* ... */],
 };
 ```
@@ -371,7 +371,7 @@ const config: Config.T<Params> = {
 Two more things are inferred from the config itself. [`schema`](#schema) types the keys and payloads of `t`/`l`, and every locale the config names — loader locales, `initLocale`, `fallbackLocale` and the keys of `translations` — completes the locale arguments and reads (`setLocale`, `loadTranslations`, `invalidate`, `l`, `locale`, `locales`):
 
 ```typescript
-const i18n = new I18n({ parser: parser(), initLocale: 'en', fallbackLocale: 'de' });
+const i18n = new I18n({ parser: parser({ onReport: null }), initLocale: 'en', fallbackLocale: 'de' });
 
 i18n.setLocale('en'); // 'en' | 'de' autocomplete here
 i18n.setLocale('sv'); // still accepted — the union is a hint, not a constraint

package/dist/types.d.ts

@@ -285,17 +285,33 @@ export declare namespace Parser {
     type Locale = Config.Locale;
     type Key = Loader.Key;
     type Output = any;
+    /**
+     * Called on the `t`/`l` path and nowhere else – never during loading,
+     * preprocessing, serialization or hydration. What it returns reaches the
+     * caller of `t`/`l` and nothing else: the core does not inspect, transform
+     * or serialize it.
+     */
     type Parse<P extends Parser.Params = Parser.Params, O = Output> = (
     /**
-     * Translation value from the definitions.
-    */
+     * Translation value from the definitions, read as an own property and
+     * already preprocessed. Arbitrary data – a string in the ordinary case and
+     * whatever a loader returned otherwise. Never `undefined`: a key resolving
+     * to no translation in the active locale nor in the fallback is answered
+     * by `fallbackValue`, and this is not called. Must not throw on whatever
+     * does arrive.
+     */
     value: Value, 
     /**
-     * Array of rest parameters given by user (e.g. payload variables etc...)
+     * The rest arguments of the `t`/`l` call. An argumentless call passes `[]`,
+     * never `undefined`; the core neither validates nor fills it in, and a
+     * `schema` narrows it at the type level only.
      */
     params: P, 
     /**
-     * Locale of translated message.
+     * Locale of translated message, normalized by `sanitizeLocales` where that
+     * yields one and as the caller spelled it otherwise. Never `undefined` –
+     * with no locale there is nothing to look up and this is not called at
+     * all.
      */
     locale: Locale, 
     /**
@@ -304,8 +320,13 @@ export declare namespace Parser {
     key: Key) => O;
     type T<P extends Parser.Params = Parser.Params, O = Output> = {
         /**
-         * Parse function deals with interpolation of user payload and returns interpolated message.
-        */
+         * Parse function deals with interpolation of user payload and returns
+         * interpolated message. The message FORMAT is the parser's own – syntax,
+         * missing-parameter rendering, pluralization, formatting and escaping are
+         * out of the core's contract and differ between parsers. What the contract
+         * requires is that none of them throws: a parser is a public edge and this
+         * package fails soft at its edges.
+         */
         parse: Parse<P, O>;
     };
     /** The parser params carried by a config's `parser`; `any` when unknown. */
@@ -382,8 +403,8 @@ export declare namespace Parser {
      * Reports the parameters a message expects. This is the BUILD-TIME half of
      * the parser contract and is deliberately not a member of `T`: a message
      * scanner attached to the runtime parser object could never be shaken out of
-     * a browser bundle. A parser ships it from its own subpath instead, and the
-     * core never calls it.
+     * a browser bundle. A parser ships it as a separate export instead – one a
+     * bundle that never reaches it drops – and the core never calls it.
      *
      * Values that are not messages the parser recognizes yield no parameters
      * rather than throwing – translation leaves are arbitrary data.
@@ -448,8 +469,15 @@ export declare namespace Schema {
 export declare namespace Translations {
     type Locales<T = string> = T[];
     type SerializedTranslations = LocaleIndexed<DotNotation.Input>;
-    type TranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never> = <K extends Schema.Key<S>>(key: K, ...restParams: Schema.Params<S, K, P>) => O;
-    type LocalTranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never, L extends string = string> = <K extends Schema.Key<S>>(locale: Config.LocaleInput<L>, key: K, ...restParams: Schema.Params<S, K, P>) => O;
+    /**
+     * What `t`/`l` yield. The parser's output on the paths that reach the parser,
+     * and a plain string on the ones that cannot: an empty key, no locale, or a
+     * config carrying no parser. `O` is `string` for every parser that returns
+     * one, which collapses the union everywhere it is not needed.
+     */
+    type Translated<O> = O | string;
+    type TranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never> = <K extends Schema.Key<S>>(key: K, ...restParams: Schema.Params<S, K, P>) => Translated<O>;
+    type LocalTranslationFunction<P extends Parser.Params = Parser.Params, O = string, S = never, L extends string = string> = <K extends Schema.Key<S>>(locale: Config.LocaleInput<L>, key: K, ...restParams: Schema.Params<S, K, P>) => Translated<O>;
     type Input<V = any> = {
         [K in any]: Input<V> | V;
     };

package/dist/utils.d.ts

@@ -9,7 +9,7 @@ export declare const translate: <P extends Parser.Params = Parser.Params, O = Pa
     locale: Translations.Locales[number] | undefined;
     fallbackLocale?: Config.FallbackLocale;
     fallbackValue?: Config.FallbackValue;
-}) => O;
+}) => Translations.Translated<O>;
 type Sanitizer = (...locales: any[]) => Config.Locale[];
 export declare const sanitizeLocales: Sanitizer;
 export declare const sanitizerFactory: (sanitize?: Config.SanitizeLocales) => Sanitizer;

package/dist/utils.js

@@ -6,8 +6,6 @@ export const hasOwn = (obj, key) => obj != null && Object.prototype.hasOwnProper
 // Own-property read: returns the value only when `key` is the object's own
 // property, otherwise undefined. Centralizes the prototype-safe table lookup.
 export const read = (obj, key) => (hasOwn(obj, key) ? obj[key] : undefined);
-// The fail-soft paths return placeholder strings (`''`, the key itself) even
-// for a parser with a non-string output — hence the `as unknown as O` casts.
 export const translate = ({ parser, key, params, translations, locale, fallbackLocale, ...rest }) => {
     if (!key) {
         logger.warn(`No translation key provided ('${locale}' locale). Skipping translation...`);
@@ -30,14 +28,14 @@ export const translate = ({ parser, key, params, translations, locale, fallbackL
             return rest.fallbackValue;
         }
         logger.warn(`No translation nor fallback found for '${key}' .`);
+        // There is nothing to interpolate, so no parser is asked to. Echoing the
+        // key is what makes a missing translation visible instead of blank.
+        return key;
     }
     if (!parser || typeof parser.parse !== 'function') {
         // Reached on every call while no parser is set (e.g. before config loads),
         // so keep it at debug to avoid flooding logs on the render path.
         logger.debug(`No parser configured. Returning raw value for '${key}' key.`);
-        // Mirror the missing-translation contract: fall back to the key itself.
-        if (text === undefined)
-            return key;
         return text;
     }
     // A key schema narrows the rest params to one key's payload — still a `P`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltekit-i18n/base",
-  "version": "3.0.0-next.3",
+  "version": "3.0.0",
   "description": "Base functionality of sveltekit-i18n library with a support for external message parsers.",
   "type": "module",
   "types": "./dist/index.d.ts",