@svelstack/translator 0.9.0 → 0.9.1

package/README.md

@@ -0,0 +1,123 @@
+# TypeSafe Internationalization
+
+Features:
+- Converting translations from YAML to .ts files
+- Loading translations from .ts files
+- Variable interpolation
+- Typechecking for keys and domains
+- Typechecking for variable interpolation
+- Pluralization support
+- Svelte5 plugin
+
+## Installation
+
+```bash
+npm i @svelstack/translator
+npm i @svelstack/translator-svelte # optional
+```
+
+## Standalone usage
+
+First, create a YAML file with translations in `translations/domain.en.yaml`:
+```yaml
+hello: 'Hello!'
+advanced:
+  hello: 'Hello, {name}!'
+```
+
+Generate dictionaries, d.ts files:
+
+```bash
+npx @svelstack/translator-extractor translations output
+```
+
+The output will be:
+```
+- dictionary
+    - en.ts
+- types.d.ts
+- dictionaries.ts
+```
+
+Create instance of Translator:
+
+```typescript
+import { Translator } from '@svelstack/translator';
+import { dictionaries } from './output/dictionaries';
+
+const translator = new Translator({
+	language: 'en',
+	fallbackLanguage: 'en',
+	dictionaries,
+});
+
+// first argument is a domain (from filename), second is a key
+console.log(translator.trans('domain', 'hello')); // Hello!
+console.log(translator.trans('domain', 'advanced.hello', { name: 'John' })); // Hello, John!
+```
+
+## Typechecking
+
+```typescript
+import { Translator } from '@svelstack/translator';
+import { dictionaries } from './output/dictionaries';
+import type { MappingForTranslator } from './output/types';
+
+export type AppTranslator = TypesafeTranslator<MappingForTranslator>;
+
+const translator = new Translator({
+	language: 'en',
+	fallbackLanguage: 'en',
+	dictionaries,
+}) as AppTranslator;
+
+translator.trans('domain', 'hello'); // IDE will suggest domains, keys and variables
+
+translator.trans('messages', 'hello'); // Error: messages is not a valid domain
+translator.trans('domain', 'hello', {}); // Error: hello does not accept variables
+translator.trans('domain', 'advanced.hello'); // Error: advanced.hello requires variables 
+translator.trans('domain', 'advanced.hello', { name: 'John', extra: '' }); // Error: unexpected variable extra
+
+```
+
+## Svelte
+
+```sveltehtml
+<script lang="ts">
+	import { SvelteTranslator, type TypesafeSvelteTranslatorConstructor } from '@svelstack/translator-svelte';
+	import { dictionaries } from './output/dictionaries';
+	import type { MappingForTranslator } from './output/types';
+	import { setContext } from 'svelte';
+
+	export const AppTranslator = SvelteTranslator as TypesafeSvelteTranslatorConstructor<MappingForTranslator>;
+
+	const translator = new AppTranslator({
+		language: 'en',
+		fallbackLanguage: 'en',
+		dictionaries,
+	});
+	
+	setContext(AppTranslator, translator);
+</script>
+
+<!-- Translations are loaded asynchronously -->
+{#await translator.wait()}
+    Loading translations...
+{:then _}
+    ....
+{/await}
+
+{translator.trans('domain', 'hello')} <!-- Fully reactive -->
+{translator.language} <!-- Fully reactive -->
+
+<button onclick={() => translator.changeLanguage('de')}>Change language</button>
+```
+
+Another component:
+```sveltehtml
+<script lang="ts">
+    const translator = AppTranslator.of();
+</script>
+
+{translator.trans('domain', 'hello')}
+```

package/dist/index.js

@@ -257,6 +257,28 @@ var PluralMessageFormatter = class {
   }
 };
 var ParameterMessageFormatter = class {
+  /** @type {RegExp} */
+  parameterRegex;
+  /** @type {string} */
+  parameterPlaceholderStart;
+  /** @type {string} */
+  parameterPlaceholderEnd;
+  /**
+   * @param {{ parameterPlaceholder: { start: string, end: string } }} settings
+   */
+  constructor(settings) {
+    this.parameterPlaceholderStart = settings.parameterPlaceholder.start;
+    this.parameterPlaceholderEnd = settings.parameterPlaceholder.end;
+    if (typeof this.parameterPlaceholderStart !== "string") {
+      throw new Error("ParameterMessageFormatter: parameterPlaceholder.start must be a string.");
+    }
+    if (typeof this.parameterPlaceholderEnd !== "string") {
+      throw new Error("ParameterMessageFormatter: parameterPlaceholder.end must be a string.");
+    }
+    const quotedStart = escapeRegExp(this.parameterPlaceholderStart);
+    const quotedEnd = escapeRegExp(this.parameterPlaceholderEnd);
+    this.parameterRegex = new RegExp(`${quotedStart}\\s*(.*?)\\s*${quotedEnd}`, "g");
+  }
   /**
    * Formats the message by replacing placeholders with parameter values.
    * @param {string} message - The message to format.
@@ -268,15 +290,18 @@ var ParameterMessageFormatter = class {
     if (parameters === void 0) {
       return message;
     }
-    return message.replace(/\{\s*(.*?)\s*}/g, (_, key) => {
+    return message.replace(this.parameterRegex, (_, key) => {
       const val = parameters[key];
       if (val == null) {
-        return `{${key}}`;
+        return `${this.parameterPlaceholderStart}${key}${this.parameterPlaceholderEnd}`;
       }
       return val.toString();
     });
   }
 };
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 // src/index.js
 var Translator = class {
@@ -304,10 +329,7 @@ var Translator = class {
    * @private
    * @type {ChainMessageFormatter}
    */
-  formatter = new ChainMessageFormatter([
-    new PluralMessageFormatter(),
-    new ParameterMessageFormatter()
-  ]);
+  formatter;
   /**
    * @param {import('./types.js').TranslatorOptions} options - Configuration options for the Translator.
    * @throws {Error} If the fallback language is not in the dictionaries.
@@ -320,6 +342,14 @@ var Translator = class {
     this._language = this.getLanguage(this.options.language);
     this.report = this.options.report || function() {
     };
+    if (Array.isArray(options.formatters)) {
+      this.formatter = new ChainMessageFormatter(options.formatters);
+    } else {
+      this.formatter = new ChainMessageFormatter([
+        new PluralMessageFormatter(),
+        new ParameterMessageFormatter({ parameterPlaceholder: { start: "{", end: "}" } })
+      ]);
+    }
     this.load(this._language);
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@svelstack/translator",
-	"version": "0.9.0",
+	"version": "0.9.1",
 	"scripts": {
 		"build": "tsup && npm run prepack",
 		"prepack": "publint",

package/src/types.d.ts

@@ -8,6 +8,7 @@ export type TranslatorOptions = {
 	dictionaries: {
 		[lang: string]: (() => Promise<Dictionary>) | Dictionary;
 	},
+	formatters?: MessageFormatter[];
 	report?: (error: any) => void;
 };