@next-box/i18n 0.0.2-alpha-3.0 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +70 -10
  3. package/package.json +2 -2
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2024 Dylan Aubrey
3
+ Copyright (c) 2024 miami-man
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -18,28 +18,80 @@ npm add @next-box/i18n
18
18
 
19
19
  ### Create content files
20
20
 
21
- Content needs to be fed into the library's `createI18n` init function in the form of a serializable object. This can be defined in a single typescript file or multiple files with a barrel file. Each language for which you have content should be a root property on the object, i.e. ```{ en: {...}, fr: {...} }```
21
+ Content needs to be fed into the library's `createI18n` init function in the form of a serializable object. Each language for which you have content should live in its own file and be structured the same way and have a `content` named export.
22
22
 
23
- The function returns an object with the `t` and `tt` content resolver functions as properties. You can then use those functions to look up content by its path from the root of the object.
23
+ Below is a simplistic example of how to define a content file that would be compatible with `createI18n`.
24
24
 
25
- Below is a simplistic example of how to define a content object that would be compatible with `createI18n`.
25
+ ```ts
26
+ // ./content.ts
27
+ export const content = {
28
+ pages: {
29
+ homepage: {
30
+ documentTitle: 'This is the homepage',
31
+ },
32
+ },
33
+ } as const; // This is important!
34
+ ```
35
+
36
+ If you were to support multiple languages, your content files might look like the examples below.
26
37
 
27
38
  ```ts
39
+ // ./content/fr/index.ts
28
40
  export const content = {
29
- en: {
30
- pages: {
31
- homepage: {
32
- documentTitle: 'This is the homepage',
33
- },
41
+ pages: {
42
+ homepage: {
43
+ documentTitle: 'Voici la page d’accueil'
44
+ },
45
+ },
46
+ } as const; // This is important!
47
+ ```
48
+
49
+ ```ts
50
+ // ./content/en/index.ts
51
+ export const content = {
52
+ pages: {
53
+ homepage: {
54
+ documentTitle: 'This is the homepage'
34
55
  },
35
56
  },
36
57
  } as const; // This is important!
37
58
  ```
38
59
 
60
+ ```ts
61
+ // ./.env.d.ts
62
+ declare namespace NodeJS {
63
+ interface ProcessEnv {
64
+ LANGUAGE_CODE: 'en' | 'fr';
65
+ }
66
+ }
67
+ ```
68
+
69
+ ```ts
70
+ // ./content/index.ts
71
+ const { LANGUAGE_CODE } = process.env;
72
+ let language: typeof import('./en/index.ts') | typeof import('./fr/index.ts');
73
+
74
+ switch (LANGUAGE_CODE) {
75
+ case 'en': {
76
+ language = await import('./en/index.ts');
77
+ break;
78
+ }
79
+
80
+ case 'fr': {
81
+ language = await import('./fr/index.ts');
82
+ break;
83
+ }
84
+ }
85
+
86
+ export const { content } = language;
87
+ ```
88
+
39
89
  Read the [typescript docs]((https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html#const-assertions)) on it for more details on `as const`.
40
90
 
41
91
  ### Create an instance of the i18n
42
92
 
93
+ `createI18n` takes the `content` object as an argument and returns an object with the `t` and `tt` content resolver functions as properties. You can then use those functions to look up content by its path from the root of the object.
94
+
43
95
  If you pass the above content into `createI18n`, you can use the `t` and `tt` functions to retrieve the `documentTitle` like in the example below.
44
96
 
45
97
  ```ts
@@ -47,10 +99,18 @@ import { createI18n } from '@next-box/i18n';
47
99
  import { content } from './content.ts';
48
100
 
49
101
  const { tt } = createI18n(content);
50
- const documentTitle = tt('en.pages.homepage.documentTitle'); // path is type-checked against the object passed into `createI18n`
51
- console.log(documentTitle); // Will log 'This is the homepage'
102
+ // Path passed into `tt` is type-checked against the object passed into `createI18n`
103
+ // Hover over `documentTitle` or `tt` and get value preview.
104
+ // This would be "This is the homepage" for the single language example.
105
+ // This would be "Films populaires" | "Popular Movies" for the multi-language example.
106
+ const documentTitle = tt('pages.homepage.documentTitle');
107
+ // Do something with `documentTitle`
52
108
  ```
53
109
 
110
+ The `t` function is an untyped content lookup. The function takes a string and returns the value that path resolves to in the i18n object passed into `createI18n`. If the function resolves no value, then it returns undefined.
111
+
112
+ The `tt` function, on the other hand, is a typed content lookup. The function takes a string that is type-checked against all the possible paths in the i18n object passed into `createI18n`. The value that path resolves to can be previewed through IDE's inbuilt Typescript type preview. If the function resolves no value, then it throws an error.
113
+
54
114
  #### Templating
55
115
 
56
116
  The `t` and `tt` functions support content with template variables. You can define template variables in content with double curley braces either side of a camelcase variable name, i.e. `Welcome back, {{fullName}}!`.
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@next-box/i18n",
3
3
  "description": "A type-safe content resolver with content path auto-complete and value preview.",
4
- "version": "0.0.2-alpha-3.0",
5
- "author": "Dylan Aubrey",
4
+ "version": "0.0.3",
5
+ "author": "miami-man",
6
6
  "license": "MIT",
7
7
  "homepage": "https://github.com/badbatch/next-box",
8
8
  "repository": {