Added loader for custom data loading such as JSON files

Updated documentation
Added feature list
Added more examples and updated those readme files.

.changeset/fifty-wasps-refuse.md

@@ -0,0 +1,5 @@
+---
+"i4n": minor
+---
+
+Allow for custom data loader to be used to get translations.

.github/README.md

@@ -28,9 +28,18 @@ npm install i4n
     - [Fallback language](#fallback-language)
   - [`switch`](#switch)
   - [Templates](#templates)
+  - [Loader](#loader)
 - [`I4nException`](#i4nexception)
 - [Examples](#examples)
 
+## Features
+
+- `t` typed function for getting translations
+- `switch` to change the language the `t` function uses.
+- fallback keys and fallback language
+- templates for easy control
+- custom data loader (for eg. JSON files)
+
 ## Usage
 
 To get started with translating, import the I4n class:
@@ -227,6 +236,43 @@ i4n.t("sayHiTo", "John"); // "Hello John"
 
 This may seem small, but this is fully typed, making it very easy to define and use your templates in your code.
 
+### Loader
+
+To use json files, it is recommended to use a custom `loader`.
+
+```ts
+async function myJsonLoader(): Promise<TranslationSet> {
+  return await import("./file-to-translations.json");
+}
+
+const i4n = new I4n<TranslationSet>({
+  loader: myJsonLoader,
+});
+```
+
+The types you pass in the `I4n` class should be the same as the loader.
+
+> 💡 Since you cannot ensure type safety on JSON files, it is recommended to use a tool like [zod](https://zod.dev/) to ensure type safety.
+
+#### `.loaded`
+
+You can then wait for the data to be loaded using the `.loaded` function:
+
+```ts
+await i4n.loaded();
+```
+
+#### `.ready`
+
+When you do not wish to block the process, you can check with the .ready if the loader has completed and the translations can be accessed.
+
+```ts
+const i4n = new I4n({...}); // with loader;
+
+// later in the program:
+i4n.ready;// boolean;
+```
+
 ## `I4nException`
 
 When using this package, be sure not to force types.
@@ -249,6 +295,8 @@ The following examples are present in this repository:
 <!-- - [**Hono.dev**](https://hono.dev/) - [examples/i4n-hono](../examples/i4n-hono/README.md) -->
 
 - [**React.dev**](https://react.dev/) - [examples/i4n-react](../examples/i4n-react/README.md)
+- [**Node.js**](https://nodejs.org/) - [examples/i4n-node](../examples/i4n-node/README.md)
+- **JSON** - [examples/i4n-json](../examples/i4n-json/README.md)
 
 <hr />
 

examples/i4n-json/README.md

@@ -0,0 +1,3 @@
+# `i4n`-json
+
+This example demonstrates how to use the `i4n` package with custom json files.

examples/i4n-json/main.ts

@@ -0,0 +1,26 @@
+import { I4n } from "i4n";
+
+interface LanguageData {
+  hello: string;
+  key?: string;
+}
+type Language = "en" | "nl";
+type TranslationSet = {
+  [lang in Language]?: LanguageData;
+};
+
+const jsonLoader = async () => await import("./translations.json");
+
+const i4n = new I4n<TranslationSet, Language>({
+  language: "en",
+  fallbackLanguage: "en",
+  loader: jsonLoader,
+});
+
+console.log(i4n.t("hello")); // "Hello"
+
+console.log("Swapping", i4n.switch("nl"));
+
+console.log(i4n.t("hello"));
+
+console.log(i4n.t("key"));

examples/i4n-json/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "i4n-node",
+  "version": "1.0.0",
+  "description": "",
+  "main": "main.ts",
+  "scripts": {
+    "start": "tsx main.ts"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "",
+  "devDependencies": {
+    "@types/node": "^22.4.0",
+    "tsx": "^4.17.0",
+    "typescript": "^5.5.4"
+  },
+  "dependencies": {
+    "i4n": "^0.4.0"
+  }
+}