feat: 🎸 functional transpiler

Author: shaharkazaz

.editorconfig

@@ -6,7 +6,7 @@ charset = utf-8
 indent_style = space
 indent_size = 2
 insert_final_newline = true
-trim_trailing_whitespace = true
+trim_trailing_whitespace = false
 
 [*.md]
 max_line_length = off

docs/docs/additional-functionality.mdx

@@ -16,7 +16,7 @@ You can point to specific keys in other keys from the same translation file. For
 
 So the result of `service.translate('fromList')` will be: "from home english".
 
-When using this feature inside a [scope](https://ngneat.github.io/transloco/docs/scope-configuration), make sure you prefix the key reference with the scope name:
+When using this feature inside a [scope](../scope-configuration)), make sure you prefix the key reference with the scope name:
 
 ```json title="admin/en.json"
 {

docs/docs/hack.mdx

@@ -46,24 +46,6 @@ export const customInterceptor = {
 };
 ```
 
-## The Transpiler
-The transpiler is responsible for resolving the given value. For example, the default transpiler transpiles `Hello {{ key }}` and replaces the dynamic variable `key` based on the given params, or the translation object.
-
-```ts
-import { TranslocoTranspiler } from '@ngneat/transloco';
-
-export class CustomTranspiler implements TranslocoTranspiler {
-  transpile(value: any, params, translation: Translation) {
-    return ...;
-  }
-}
-
-export const customTranspiler = {
-  provide: TRANSLOCO_TRANSPILER,
-  useClass: CustomTranspiler
-}
-```
-
 ## Missing Handler
 
 This handler is responsible for handling missing keys. The default handler calls `console.warn()` with the key when config.isProdMode is set to `false`, and returns an empty string to use as a replacement for the missing key's value.

docs/docs/loading-template.mdx

@@ -4,7 +4,7 @@ title: Loading Template
 
 Transloco provides you with a way to define a loading template, that will be used while the translation file is loading.
 
-Similarly to the previous examples, set the `TRANSLOCO_LOADING_TEMPLATE` provider either in lazy module providers, component providers, in the template, or even in the `app.module` itself (affecting the entire app).
+Similarly to the previous examples, set the `TRANSLOCO_LOADING_TEMPLATE` provider either in lazy module providers, component providers, in the template, or even in the `AppModule` itself (affecting the entire app).
 
 For example:
 

docs/docs/plugins/message-format.mdx

@@ -15,7 +15,7 @@ npm i messageformat @ngneat/transloco-messageformat
 ```
 
 ## Usage
-The `MessageFormatTranspiler` is compatible with the DefaultTranspiler and therefore you can switch without worry that it will break your current translations.
+The `MessageFormatTranspiler` is compatible with the `DefaultTranspiler` and therefore you can switch without worry that it will break your current translations.
 
 It then enables support for the following within youIt enables support for the following within your i18n translation files:
 
@@ -26,7 +26,7 @@ It then enables support for the following within youIt enables support for the f
 }
 ```
 
-To enable this plugin, add the following to the imports array in your `app.module.ts`:
+To enable this plugin, add the following import in your `TranslocoRootModule`:
 
 ```ts title="transloco-root.module.ts"
 import { TranslocoMessageFormatModule } from '@ngneat/transloco-messageformat';

docs/docs/translation-in-template.mdx

@@ -47,7 +47,7 @@ Let's say we need to use the `dashboard` scope all over the template. Given this
 ```json title="en.json"
 {
   "foo": "Foo",
-  "bar": "Bar"
+  "bar": "Bar",
   "dashboard": {
     "title": "Dashboard Title",
     "desc": "Dashboard Desc"

docs/docs/transpiler.mdx

@@ -0,0 +1,119 @@
+---
+title: The Transpiler
+---
+
+The transpiler is responsible for resolving the given value.  
+For example, when given `Hello {{ key }}` the default transpiler will replace the dynamic variable `key` based on the given params, or the translation object.
+
+## Functional Transpiler
+
+In addition to the default transpiler Transloco also exposes the `FunctionalTranspiler` which allows you to implement function calls into your translation values.  
+This way you can leverage Angular's DI power and make you translations even more flexible.
+
+The `FunctionalTranspiler` is compatible with the `DefaultTranspiler` and therefore you can switch without worry that it will break your current translations.
+
+To enable this transpiler, add the following provider in your `TranslocoRootModule`:
+
+```ts title="transloco-root.module.ts"
+import { Injector } from '@angular/core'
+import { FunctionalTranspiler, TRANSLOCO_TRANSPILER } from '@ngneat/transloco';
+
+@NgModule({
+  ...
+  providers: [{
+    provide: TRANSLOCO_TRANSPILER,
+    useClass: FunctionalTranspiler,
+    deps: [Injector]
+  }]
+})
+export class TranslocoRootModule {}
+```
+
+### Usage
+
+In order to use a function in the translation we need to provide it to the transpiler.  
+We do so by creating a new class that implements the `TranslocoTranspilerFunction` interface.  
+For example, let's say we want to display different texts in case the user has a specific feature exposed or not:
+
+```ts title="has-feature-flag.ts"
+import { FFService } from './feature-flag.service';
+import { TranslocoTranspilerFunction } from '@ngneat/transloco';
+
+class FeatureFlagResolver implements TranslocoTranspilerFunction {
+  constructor(private featureFlagService: FFService) {}
+  
+  transpile(...args: string[]): any {
+    const [flagName, trueValue, falseValue] = args;
+    
+    return this.featureFlagService.hasFF(flagName) ? trueValue : falseValue;
+  }
+}
+```
+As you can see the `transpile` function can accept any number of arguments, you are the one who defines which arguments will be passed. In my case I'm passing 3:
+* The feature flag's name.
+* The value I want to present in case the user has the flag.
+* The value I want to present in case the user doesn't have the flag.
+
+Now we will add this transpiler function to the `TranslocoRootModule` providers:
+
+```ts title="transloco-root.module.ts"
+import { Injector } from '@angular/core'
+import { FunctionalTranspiler, TRANSLOCO_TRANSPILER } from '@ngneat/transloco';
+import { FeatureFlagResolver } from './has-feature-flag';
+
+@NgModule({
+  ...
+  providers: [{
+    provide: TRANSLOCO_TRANSPILER,
+    useClass: FunctionalTranspiler,
+    deps: [Injector]
+  },
+  {
+    provide: 'hasFeatureFlag', // ====> The function name used in the translation
+    useClass: FeatureFlagResolver
+  }],
+})
+export class TranslocoRootModule {}
+```
+
+The functional syntax is very similar to calling a regular function, here is an example:
+
+```json title="en.json"
+{
+  "title": "[[ hasFeatureFlag(newDashboards, has flag, missing flag) ]]",
+}
+```
+
+In this case we are checking if the use has `newDashboard` flag, in case he does, we want to display  
+`'has flag'` and otherwise we will display `'missing flag'`.
+
+### Usage Notes 
+
+If the function returns a string that includes the interpolation syntax (`{{value}}`), the transpiler will replace it with the `params` or [other keys references](../additional-functionality#reference-other-keys) just like the default.
+
+If you function param needs to include a comma you need to escape it:
+```json title="en.json"
+{
+  "title": "[[ someFunc(Hello {{user}}\\, welcome ,...) ]]",
+}
+```
+`'Hello {{user}}, welcome'` will be the first param passed.
+
+## Custom Transpiler
+
+You can also provide a custom transpiler by creating a class that implements the `TranslocoTranspiler` interface.
+
+```ts
+import { TranslocoTranspiler } from '@ngneat/transloco';
+
+export class CustomTranspiler implements TranslocoTranspiler {
+  transpile(value: any, params, translation: Translation) {
+    return ...;
+  }
+}
+
+export const customTranspiler = {
+  provide: TRANSLOCO_TRANSPILER,
+  useClass: CustomTranspiler
+}
+```

docs/docusaurus.config.js

@@ -41,8 +41,9 @@ module.exports = {
         },
         {
           href: 'https://stackblitz.com/edit/ngneat-transloco',
-          label: 'Playground ↗',
-          position: 'left'
+          label: 'Playground',
+          position: 'left',
+          className: 'header-playground-link'
         },
         {
           href: 'https://gitter.im/ngneat-transloco/lobby',

docs/sidebars.js

@@ -42,6 +42,10 @@ module.exports = {
       type: 'doc',
       id: 'loading-template'
     },
+    {
+      type: 'doc',
+      id: 'transpiler'
+    },
     {
       type: 'doc',
       id: 'hack'

docs/src/css/custom.css

@@ -24,6 +24,10 @@
   padding: 0 var(--ifm-pre-padding);
 }
 
+[data-theme='dark'] .docusaurus-highlight-code-line {
+  background-color: rgb(46, 47, 75);
+}
+
 code {
   background-color: rgba(255, 229, 100, 0.2);
   color: #1a1a1a;
@@ -192,6 +196,22 @@ header iframe {
     no-repeat;
 }
 
+.header-playground-link {
+  display: flex;
+}
+
+.header-playground-link:after {
+  background: url("data:image/svg+xml;charset=utf-8,%3Csvg width='10' height='10' viewBox='0 0 32 32' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M29.9984 2.92009C29.9543 1.81641 29.0238 0.957482 27.9201 1.00163L9.93446 1.72105C8.83077 1.7652 7.97185 2.6957 8.01599 3.79939C8.06014 4.90308 8.99064 5.76201 10.0943 5.71786L18.047 5.37359L20.1625 7.57369L2.5304 27.6435C1.7812 28.4551 1.83181 29.7204 2.64345 30.4696C3.45509 31.2188 4.72041 31.1682 5.46962 30.3566L23.3959 10.9365L26.4426 14.1051L26.721 21.0656C26.7652 22.1693 27.6957 23.0282 28.7994 22.9841C29.9031 22.9399 30.762 22.0094 30.7178 20.9057L29.9984 2.92009Z' fill='black'/%3E%3C/svg%3E")
+    no-repeat center;
+  content: '';
+  width: 24px;
+  height: 24px;
+}
+[data-theme='dark'] .header-playground-link:after {
+  background: url("data:image/svg+xml;charset=utf-8,%3Csvg width='10' height='10' viewBox='0 0 32 32' fill='none' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M29.9984 2.92009C29.9543 1.81641 29.0238 0.957482 27.9201 1.00163L9.93446 1.72105C8.83077 1.7652 7.97185 2.6957 8.01599 3.79939C8.06014 4.90308 8.99064 5.76201 10.0943 5.71786L18.047 5.37359L20.1625 7.57369L2.5304 27.6435C1.7812 28.4551 1.83181 29.7204 2.64345 30.4696C3.45509 31.2188 4.72041 31.1682 5.46962 30.3566L23.3959 10.9365L26.4426 14.1051L26.721 21.0656C26.7652 22.1693 27.6957 23.0282 28.7994 22.9841C29.9031 22.9399 30.762 22.0094 30.7178 20.9057L29.9984 2.92009Z' fill='white'/%3E%3C/svg%3E")
+    no-repeat center;
+}
+
 [data-theme='dark'] .header-gitter-link:before {
   background: url("data:image/svg+xml;charset=utf-8,%3Csvg version='1.1' fill='white' xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' viewBox='0 0 18 25' class='logo-gitter-sign' data-v-44ebcb1a=''%3E%3Crect x='15' y='5' width='2' height='10'%3E%3C/rect%3E%3Crect x='10' y='5' width='2' height='20'%3E%3C/rect%3E%3Crect x='5' y='5' width='2' height='20'%3E%3C/rect%3E%3Crect width='2' height='15'%3E%3C/rect%3E%3C/svg%3E")
     no-repeat;