cloudflare-next-intl 0.7.0 → 0.7.1

package/README.md

@@ -96,6 +96,14 @@ export default async function Page() {
 }
 ```
 
+`t(key)` always returns a `string`. For a message whose value is an array
+or nested object (e.g. a list), use `t.raw(key)` to get it back as-is:
+
+```tsx
+const t = await getTranslations("Index");
+const items = t.raw("items") as string[]; // messages.Index.items
+```
+
 ### Client Components
 
 ```tsx

package/dist/src/general/cache_variables.bench.js

@@ -13,7 +13,9 @@ describe('cache_variables', () => {
         getMessageCache(undefined);
     });
     bench('setTranslationCache + getTranslationCache hit', () => {
-        setTranslationCache('en-common', (k) => k);
+        const fn = (k) => k;
+        fn.raw = (k) => k;
+        setTranslationCache('en-common', fn);
         getTranslationCache('en-common');
     });
 });

package/dist/src/general/general_functions.js

@@ -18,6 +18,7 @@ const errorAndReturnFallback = (message, cacheKey, locale, namespace, key) => {
     ].filter(Boolean); // Filter out empty parts
     console.error(parts.join(' | '));
     const fallbackFn = (k) => k; // Fallback function simply returns the key
+    fallbackFn.raw = (k) => k;
     setTranslationCache(cacheKey, fallbackFn);
     return fallbackFn;
 };
@@ -29,10 +30,10 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
     // Traverse the translation object based on the namespace parts.
     for (let i = 0; i < namespaceParts.length; i++) {
         const part = namespaceParts[i];
-        const nextLevel = currentLevel[part];
+        const nextLevel = Array.isArray(currentLevel) ? undefined : currentLevel[part];
         if (i === namespaceParts.length - 1) {
             // Last part of the namespace, should resolve to an object (the base for translations).
-            if (typeof nextLevel === 'object' && nextLevel !== null) {
+            if (typeof nextLevel === 'object' && nextLevel !== null && !Array.isArray(nextLevel)) {
                 translationsBase = nextLevel;
             }
             else {
@@ -77,7 +78,7 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
                 console.warn(`Translation key "${key}" in namespace "${namespace}" leads to a string prematurely at "${part}" for locale "${locale}".`);
                 return key; // Return the key as fallback
             }
-            const value = currentTranslation[part];
+            const value = Array.isArray(currentTranslation) ? undefined : currentTranslation[part];
             if (i === keyParts.length - 1) {
                 if (typeof value !== 'string') {
                     console.warn(`Translation key "${key}" in namespace "${namespace}" resolves to a non-string value for locale "${locale}". Expected string, got "${typeof value}".`);
@@ -104,6 +105,68 @@ export function getTranslationsImpl(locale, messages, namespace, cacheKey) {
         console.warn(`Translation key "${key}" in namespace "${namespace}" is missing or not a string for locale "${locale}".`);
         return key; // Return the key as fallback
     };
+    /**
+     * `t.raw(key)` — the escape hatch for when a message value isn't a
+     * plain string.
+     *
+     * `t(key)` (the main `translateFunction` above) ALWAYS returns a
+     * `string`; if the value at `key` is an array or a nested object, it
+     * warns and falls back to returning `key` itself. Use `t.raw(key)`
+     * instead whenever your `messages/<locale>.json` stores a list or
+     * object under that key (e.g. a list of social links, a table of
+     * FAQ entries, a settings sub-object) — it returns the value exactly
+     * as it appears in the JSON, unmodified: string stays string, array
+     * stays array, object stays object.
+     *
+     * Mirrors `next-intl`'s `t.raw` API, so existing `next-intl` knowledge
+     * transfers directly.
+     *
+     * @example
+     * // messages/en.json: { "Index": { "items": ["a", "b", "c"] } }
+     * const t = await getTranslations("Index");
+     * const items = t.raw("items") as string[]; // ["a", "b", "c"]
+     *
+     * @param key Dot-separated path into the resolved namespace, same
+     *   format as `translateFunction`'s `key` (e.g. `"items"` or
+     *   `"section.list"`).
+     * @returns The raw `TranslationEntry` at `key` (string | object | array),
+     *   or `key` itself if the path doesn't resolve (missing key, or an
+     *   intermediate segment isn't an object) — matching `translateFunction`'s
+     *   fallback-to-key behavior on lookup failure.
+     */
+    const rawFunction = (key) => {
+        const keyParts = key.split('.');
+        let currentTranslation = translationsBase;
+        for (let i = 0; i < keyParts.length; i++) {
+            const part = keyParts[i];
+            if (typeof currentTranslation === 'string' || Array.isArray(currentTranslation)) {
+                console.warn(`Translation key "${key}" in namespace "${namespace}" leads to a non-object prematurely at "${part}" for locale "${locale}".`);
+                return key;
+            }
+            const value = currentTranslation[part];
+            if (i === keyParts.length - 1) {
+                if (value === undefined) {
+                    console.warn(`Translation key "${key}" in namespace "${namespace}" is missing for locale "${locale}".`);
+                    return key;
+                }
+                return value;
+            }
+            else {
+                if (typeof value === 'object' && value !== null) {
+                    currentTranslation = value;
+                }
+                else {
+                    console.warn(`Translation key "${key}" in namespace "${namespace}" has invalid structure at "${part}" for locale "${locale}". Expected object, got "${typeof value}".`);
+                    return key;
+                }
+            }
+        }
+        return key;
+    };
+    // Attach `.raw` onto the same callable function object so callers get
+    // one value that works both as `t(key)` and `t.raw(key)`, exactly like
+    // `next-intl`'s translator shape.
+    translateFunction.raw = rawFunction;
     setTranslationCache(cacheKeyValue, translateFunction);
     return translateFunction;
 }

package/dist/src/types/types.d.ts

@@ -714,12 +714,30 @@ export interface CookieAttributes {
      */
     secure?: boolean | undefined;
 }
-export type TranslationEntry = string | TranslationObject;
+export type TranslationEntry = string | TranslationObject | TranslationEntry[];
 export interface TranslationObject {
     [key: string]: TranslationEntry;
 }
 export type ReturnType = string;
-export type TranslatorReturnType = (key: string) => ReturnType;
+export interface TranslatorReturnType {
+    /** Looks up `key` and coerces it to a `string`. If the value at `key` isn't a plain string (it's an array or object), this warns and returns `key` itself — use {@link TranslatorReturnType.raw} for those cases instead. */
+    (key: string): ReturnType;
+    /**
+     * Escape hatch for non-string message values. `t(key)` always returns a
+     * `string` and can't represent arrays/objects; `t.raw(key)` returns the
+     * value exactly as stored in `messages/<locale>.json` — string, array,
+     * or nested object, unmodified. Use it whenever a message is a list
+     * (e.g. social links, FAQ entries) rather than plain text. Mirrors
+     * `next-intl`'s `t.raw`, so existing `next-intl` usage patterns apply
+     * as-is.
+     *
+     * @example
+     * // messages/en.json: { "Index": { "items": ["a", "b", "c"] } }
+     * const t = await getTranslations("Index");
+     * const items = t.raw("items") as string[]; // ["a", "b", "c"]
+     */
+    raw(key: string): TranslationEntry;
+}
 export type changeFrequency = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never' | undefined;
 export type Alternates = {
     languages?: Languages<string> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",