DigiComp.FlowTranslationEnd.../README.md

# DigiComp.FlowTranslationEndpoint

![Build status](https://ci.digital-competence.de/api/badges/Packages/DigiComp.FlowTranslationEndpoint/status.svg)

This package is designed to help bringing needed translations to javascript components, without pushing them to the DOM in your views.

Other solutions, which would generate files available for usage in client scope, have the disadvantage that one would have to repeat the relativ complex overriding and merging logic of Flow. With this endpoint you can get the same content, as you would get, if you call the translation service with your translation id.

The main components are a `CurrentHtmlLangViewHelper`, which is intended to be used to fill the `lang` attribute of the `html` tag, so the frontend knows, which language is currently active (and is good practice anyway) and a `TranslationRequestMiddleware`, which will respond to any request, where the request path equals `DigiComp.FlowTranslationEndpoint.reactOnPath` (Default: "/xliff-units"), and search for unit patterns in the `DigiComp.FlowTranslationEndpoint.getParameterName` (Default: "idPatterns").

"idPatterns" is built with following syntax:
`packageName:catalogName|SEARCH_REGEX, ANOTHER PATTERN...`

For example:
````
GET /xliff-units?idPatterns=Neos.Flow:Main|authentication.*
````

would return all translation keys from the main unit of `Neos.Flow` starting with "authentication" and would look like that:

```json
{
    "Neos.Flow:Main": {
        "authentication.required": "Authentication required", 
        "authentication.username": "Username",
        "authentication.password": "Password", 
        "authentication.new-password": "New password",
        "authentication.login": "Login", 
        "authentication.logout": "Logout"
    }
}
```

To let the middleware know, in which langauge the translated units should be, you should set the correct `Accept-Language`-Header with your request, which you obtained from the `lang` attribute of the `html` element.

Given your HTML head looks like that:
```html
<html lang="{translation:currentHtmlLang()}" data-xliff-uri="{translation:uri()}" data-xliff-parameter="{translation:parameterName()}">
```

Your JavaScript could look like that:

```javascript
async function translate(idPatterns) {
    const uri = new URL(document.documentElement.dataset.xliffUri, document.location);
    uri.searchParams.set(document.documentElement.dataset.xliffParameter, idPatterns);
    const response = await fetch(uri, {headers: {
        'Accept': 'application/json',
        'Accept-Language': document.documentElement.lang,
    }});
    if (! response.ok) {
        return Promise.reject('Unexpected server response');
    }
    return await response.json();
}
```
Last but not least:
Do not forget to have a lot of fun.
First version, extracted and tested 2023-08-05 15:49:46 +02:00			`# DigiComp.FlowTranslationEndpoint`

			`![Build status](https://ci.digital-competence.de/api/badges/Packages/DigiComp.FlowTranslationEndpoint/status.svg)`

			`This package is designed to help bringing needed translations to javascript components, without pushing them to the DOM in your views.`

			`Other solutions, which would generate files available for usage in client scope, have the disadvantage that one would have to repeat the relativ complex overriding and merging logic of Flow. With this endpoint you can get the same content, as you would get, if you call the translation service with your translation id.`

As the tests shown, that the custom parameter breaks browser based caching, we now enforce the 'traditional url' approach and added cache control information for the browser 2023-08-08 17:02:13 +02:00			The main components are a `CurrentHtmlLangViewHelper`, which is intended to be used to fill the `lang` attribute of the `html` tag, so the frontend knows, which language is currently active (and is good practice anyway) and a `TranslationRequestMiddleware`, which will respond to any request, where the request path equals `DigiComp.FlowTranslationEndpoint.reactOnPath` (Default: "/xliff-units"), and search for unit patterns in the `DigiComp.FlowTranslationEndpoint.getParameterName` (Default: "idPatterns").
First version, extracted and tested 2023-08-05 15:49:46 +02:00
Better documentation for the lessons learned 2023-08-08 17:28:14 +02:00			`"idPatterns" is built with following syntax:`
			`packageName:catalogName\|SEARCH_REGEX, ANOTHER PATTERN...`

First version, extracted and tested 2023-08-05 15:49:46 +02:00			`For example:`
			````
As the tests shown, that the custom parameter breaks browser based caching, we now enforce the 'traditional url' approach and added cache control information for the browser 2023-08-08 17:02:13 +02:00			`GET /xliff-units?idPatterns=Neos.Flow:Main\|authentication.*`
First version, extracted and tested 2023-08-05 15:49:46 +02:00			````

			would return all translation keys from the main unit of `Neos.Flow` starting with "authentication" and would look like that:

			```json
			`{`
			`"Neos.Flow:Main": {`
			`"authentication.required": "Authentication required",`
			`"authentication.username": "Username",`
			`"authentication.password": "Password",`
			`"authentication.new-password": "New password",`
			`"authentication.login": "Login",`
			`"authentication.logout": "Logout"`
			`}`
			`}`
			```

			To let the middleware know, in which langauge the translated units should be, you should set the correct `Accept-Language`-Header with your request, which you obtained from the `lang` attribute of the `html` element.

Better documentation for the lessons learned 2023-08-08 17:28:14 +02:00			`Given your HTML head looks like that:`
			```html
			`<html lang="{translation:currentHtmlLang()}" data-xliff-uri="{translation:uri()}" data-xliff-parameter="{translation:parameterName()}">`
			```

First version, extracted and tested 2023-08-05 15:49:46 +02:00			`Your JavaScript could look like that:`

			```javascript
			`async function translate(idPatterns) {`
Better documentation for the lessons learned 2023-08-08 17:28:14 +02:00			`const uri = new URL(document.documentElement.dataset.xliffUri, document.location);`
			`uri.searchParams.set(document.documentElement.dataset.xliffParameter, idPatterns);`
As the tests shown, that the custom parameter breaks browser based caching, we now enforce the 'traditional url' approach and added cache control information for the browser 2023-08-08 17:02:13 +02:00			`const response = await fetch(uri, {headers: {`
			`'Accept': 'application/json',`
			`'Accept-Language': document.documentElement.lang,`
Adding error handling to code example 2023-08-08 10:48:14 +02:00			`}});`
			`if (! response.ok) {`
			`return Promise.reject('Unexpected server response');`
			`}`
			`return await response.json();`
First version, extracted and tested 2023-08-05 15:49:46 +02:00			`}`
			```
As the tests shown, that the custom parameter breaks browser based caching, we now enforce the 'traditional url' approach and added cache control information for the browser 2023-08-08 17:02:13 +02:00			`Last but not least:`
			`Do not forget to have a lot of fun.`