DEV Community: Sebastian Helzle

The translation helper in Neos CMS

Sebastian Helzle — Tue, 09 Feb 2021 12:16:15 +0000

Neos CMS has a very powerful translation helper in its own rendering language Fusion. It can handle simple translations matching the users language but also more complex localisation options for plural forms and to fill placeholders.
All features derive directly from the the i18n & l10n framework provided by Neos underlying PHP framework Flow.

The translation helper

Usually the helper is called in its shorthand form like this:

myLabel = ${I18n.translate('Vendor.Package:Main:component.label')}

This call means, that in the Vendor.Package package a Resources/Private/Translations/en folder exists. Where "en" stands for an English variant and I just used as an example. If you use a different or more languages (and their variants) you should have a folder for each language code.
For our example each language folder would contain at least one file called Main.xlf and it contains an entry for the id component.label.

The text for that entry is retrieved and myLabel will contain it. When the user uses a different language and a translation exists, the correct label will be retrieved. If not, a fallback chain is triggered.
The file is structured like this:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file original="" product-name="Vendor.Package" source-language="en" datatype="plaintext">
        <body>
            <trans-unit id="component.label">
                <source>My component</source>
            </trans-unit>
        </body>
    </file>
</xliff>

Each trans-unit is a translation unit that can be retrieved in Fusion.

When having multiple languages defined, the Flow Framework used by Neos will provide the correct translation based on the current frontend language dimension and defined fallback chain.

The translation file in another language other than the default would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file original="" product-name="Vendor.Package" source-language="en" target-language="de" datatype="plaintext">
        <body>
            <trans-unit id="component.label">
                <source>My component</source>
                <target>Meine Komponente</source>
            </trans-unit>
        </body>
    </file>
</xliff>

It defines the target language and has a target entry for each unit.

Using arguments and quantities

The translation helper also allows you to provide named and unnamed arguments. This allows you to use placeholders in your text. For named arguments you could use a placeholder like {amount} to show the number of items in the middle of a text. And in another language the placeholder could be at the end.
Unnamed arguments can be inserted by their index. So the first item would be assigned via {0} and so on. I always recommend to use named arguments, as it makes managing those translations so much easier. Especially when there are more arguments.

You can also provide a quantity. This would allow use to not only have a variable in our text like described above, but also have text variants based on the number itself. Many languages have variants for 0, 1 or more items. Some languages have even more differentiations.

Here is an example of an xliff file using quantities and arguments:

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
    <file original="" product-name="Vendor.Package" source-language="en" target-language="de" datatype="plaintext">
        <body>
            <group id="some.label" restype="x-gettext-plurals">
                <trans-unit id="component.label[0]">
                    <source>You see {amount} item</source>
                    <target>Du siehst {amount} Element</source>
                </trans-unit>               
                <trans-unit id="component.label[1]">
                    <source>You see {amount} items</source>
                    <target>Du siehst {amount} Elemente</source>
                </trans-unit>
            </group>
        </body>
    </file>
</xliff>

Using the helper

The translation helper looks in its full form like this:

translate($id, $originalLabel = null, array $arguments = [], $source = 'Main', $package = null, $quantity = null, $locale = null)

You can use it in Fusion like this:

amount = 5
myAmountLabel = ${I18n.translate('component.amount', '{amount} Items', { amount: this.amount }, 'Main', 'Vendor.Package', this.amount)}

Every argument of the helper that has a default value can be skipped if not needed. But usually you have to set most to make sure that the translation is fetched from the correct package. As the framework assumes Neos.Neos as default package name (in the Neos CMS context).

A less cluttered variant

The translation helper also has another method that provides a TranslationParameterToken.

You can generate one with this call:

myLabel = ${I18n.id('component.label')}

Or this one:

myLabel = ${I18n.value('My component')}

But this will not yet return a valid translation. The token that is returned provides more methods that can be chained. To make it fully work we again need to provide the same parameters as we did with the previous calls:

myLabel = ${I18n.id('component.label').package('Vendor.Package').source('Main').translate()}

So what did we gain? Nothing yet.

But if we don‘t call translate() at the end we can reuse our token:

i18n = ${I18n.id('').package('Vendor.Package').source('Main')}
myLabel = ${this.i18n.id('component.label').translate()}
myOtherLabel = ${this.i18n.value('Other label').translate()}

As you see, we can now skip setting the package and source over and over again.
This approach is quite helpful when you use the helper with AFX and the code is less cluttered.

Note: If you skip the translate() at the end it will still work correct in most cases as the token has a toString() implementation. But being explicit can prevent unforeseen errors.

It‘s always good to have a look at the implementation of the helper. Maybe you spot some more nice features that help you in your project.

Please contact me if you do and I can add some more hints to this post.
Translating by value

You might have seen that you can also retrieve translation by their text instead of an id. My personal experience is that this can cause problems when the text changes, meanings change or duplicates appear. So I only use and recommend unique ids. And you can still derive the meaning in the code by providing fallback values if a translation is not available.
Using the helper without Fusion

If you have Fluid templates, you have a similar helper there. It looks like this:

<f:translate id="label.id"/>

If you write JavaScript for custom Neos UI plugins or backend modules you can also use the JS version of the helper.
It is available in the Neos.UI via the i18nRegistry. And in backend modules as global object:

window.NeosCMS.I18n.translate()

Summary

Translating labels in Neos allows more flexibility than you might know. Use the token form, quantities and named arguments to make it easier to maintain your code and provide better translations & localisations which take the user into account.

My 10 most favourite Neos CMS settings you might not know yet

Sebastian Helzle — Fri, 15 May 2020 06:45:39 +0000

Very often I copy & paste settings from existing projects as I need them for most new projects. Or I help other people when they wonder how to achieve certain things in Neos.
To make things easier, here is a list of my top 10 settings in Flow & Neos CMS.
You can add them to your main Settings.yaml of your site package or create additional Settings.XYZ.yaml files where XYZ matches the topic of the settings it contains.

1. Disable session timeout during development

Neos:
  Flow:
    session:
      inactivityTimeout: 0

Annoyed when the Neos backend bothers you with a login popup when just wanted to test your new content element?
This will make sure that your backend session is still alive while you've been busy implementing your changes.

You can put this setting into Development/Settings.yaml in your Configuration folder, so it's only loaded during development.

2. Change default languages and fallbacks

Neos:
    Flow:
        i18n:
            defaultLocale: de
            fallbackRule:
                order: ['fr', 'en']
    Neos:
        userInterface:
            defaultLanguage: de

Changes on the one hand the order in which translations and their fallbacks are loaded for plugins and other frontend code. But also the default backend interface language for new users.
Don't forget the fallbackRule or you might even get errors when your language has missing translations in some package.

3. Define global image quality

Neos:
    Media:
        image:
            defaultOptions:
                quality: 95
                webp_quality: 95
                jpeg_quality: 95
                png_compression_level: 95

Defines the default image quality that the configured image library in Neos will use.

4. Remove application version from HTTP header

Neos:
    Flow:
        http:
            applicationToken: ApplicationName

By default the version of Flow & Neos is contained in the HTTP header. With this setting it will just say "Flow Neos".

5. Define initial tree loading depth

Neos:
    Neos:
        userInterface:
            navigateComponent:
                nodeTree:
                    loadingDepth: 1
                structureTree:
                    loadingDepth: 2

This setting decreases the initial loading depth which can help with large or complex trees and long loading times.
If you have long loading times. Maybe you want to look into using ElasticSearch for querying the page tree.

6. Define responsive previews for the backend

Neos:
    Neos:
        userInterface:
            editPreviewModes:
                iphone:
                    isEditingMode: false
                    isPreviewMode: true
                    fusionRenderingPath: ''
                    title: 'iPhone'
                    position: 100
                    width: 375px
                    height: 667px
                    backgroundColor: 'black'
                ipad:
                    isEditingMode: false
                    isPreviewMode: true
                    fusionRenderingPath: ''
                    title: 'iPad - landscape'
                    position: 100
                    width: 1024px
                    height: 768px
                    backgroundColor: 'black'

These settings allow you to add additional preview modes in the backend to see how the selected page will look on small to large devices.

7. Additional groups for the creation dialog

Neos:
    Neos:
        nodeTypes:
            groups:
                myAdditionalTypes:
                    position:'end'
                    label: 'My additional rarely used types'
                    collapsed: true

You have a lot of node types? Group them in a smart way and initially collapse groups with rarely needed types.

8. Disable html suffix in URL generation

Neos:
    Flow:
        mvc:
            routes:
                'Neos.Neos':
                    variables:
                        defaultUriSuffix: ''

Bored of ".html" at the end of your urls? Disable it!
But don't do it in production without a redirect mechanism ;)

9. Spot untranslated labels in the backend

Neos:
    Neos:
        userInterface:
            scrambleTranslatedLabels: true

Only do this during development!
It will scramble all labels that are using the translation mechanism in Flow / Neos.
Everything that can still be read is either your data or untranslated labels.

10. Customize your login screen

Neos:
    Neos:
        backendLoginForm:
            backgroundImage: 'resource://My.Site/Public/Images/Login/MyLoginScreen.jpg'
            stylesheets:
                'My.Site:LoginStyles': 'resource://My.Site/Public/Styles/Login.css'

You don't like are beautiful login background in each Neos version? Or you want to keep the one you like the most? Or you want to have your customer see something related to their company?
Simply change the background image to your liking.
You can even add your own stylesheet to override the Neos logo or make other changes.
Summary

There are a lot of settings in the Flow & Neos core packages. But the ones I mentioned should solve the most common issues.
But it's always a good idea to go into the Settings.yaml files of the packages you use and have a look around. Maybe you spot a helpful setting too!

Learn more about my work or Neos CMS.

How to use "meta"-sprints in Jira to simplify your Scrum process

Sebastian Helzle — Wed, 18 Dec 2019 09:39:11 +0000

Many companies use Jira to organise their backlog and to plan sprints. Due to constraints in the software and what happens in everyday Scrum live, this creates some issues for which I present a workaround that solved them during my time as Product Owner.

Currently I’m spending a large part of my working time as a consultant in a Scrum team at a large telecommunications company.

I’m mostly focused on helping them building modules and components for their Neos CMS installation. But as part of their team, I’m also following closely how they work with Scrum and related tools.

In the last 6 years I worked as Product Owner and in other Scrum roles at an agency. I learnt a lot and I also found good solutions for the issues one has, when trying to have a synchronous digital representation your processes. The concept I will explain should also work perfectly fine with any other tool that supports putting stories into sprints.

Why the default sprint list wasn’t enough

At the agency we also worked with Jira and I had to make sure that our customers and my team were able to look at the shared Jira boards and understand what currently happens and what each of them has to do. I also wanted to minimise the chance for errors as that would have led to mistakes, loosing track of important tasks and finally also an increasing amount of work for me to keep track of everything.

Each customer would have their own board where they can see their backlog, stories that are being prepared and stories that are being worked on. They would prioritise in their board and synchronise this with me, so we could would work on the most important and valuable tasks for their project.

Internally we would have one board which combined the stories of all the customers (5+) my team worked for. They needed a way to immediately understand what to do next and what they needed to take care of during refinements and plannings. I could always have told them what to do next, but that would have meant, that I needed to remember everything. They would also have a problem, when I’m not there. So over 2 years I worked with our customers and the team on several iterations of „meta“-sprints that would organise the stories in our board in a way that made sense to everyone involved. At the end I had a structure that worked for everybody and I rarely needed to tell anyone where to put new stories or what to work on in the sprint meetings.
I just had to make sure that I prioritised the shared board to make sure that each customers stories where in the right place in relation to each other, and keeping a good overview which stories were coming up that had a high priority.

Different place - same problems

At the mentioned company we currently only work on one project, but it has a very high complexity with many components, dependencies to other teams and stakeholders. During the first few planning sessions and refinements I realised they basically had the same issues as we had with our agency work. People are not always sure where to put stories, what to work on in a meeting and a high dependency on the Product Owner. And there is one ongoing issue with Jira which can cause trouble when you finish a sprint and your unfinished stories get mixed up with the ones already put into the next sprint. I understand from a technical perspective that it’s hard for Jira to find the right spot for each story, especially if you organise them with several boards, but it’s still annoying and can cost a lot of time to sort things the right way again. That’s worse when you have the whole team sitting there and waiting.

To explain my sprints in a more visual way I set up a simple Jira cloud trial and created some sprints and stories that will help my future rocket startup to fly to the moon and make me rich.

First I will start almost at the bottom, just above the „Backlog“.

The „Upcoming“-sprint

When you work on projects for many years, your backlog can fill up with all kinds of stories. Some people say you should just remove everything that has a certain age, but when working with several customers that can cause diplomatic issues that are sometimes not worth to fight for. So I accepted that we have a certain amount of „zombie“-stories that might at some point happen or they won’t. This lead me to create the first „meta“-sprint. The one called „Upcoming“ (thanks to a certain other PO for coming up with a better name than I did!). This separates the usual backlog from stories that are actually relevant in the foreseeable future or stories that just temporarily fell out of the priority due to some stakeholders decision. I tried keeping the amount of stories in this sprint under 20 to not lose track and create yet another „zombie“ backlog.

As you see in the screenshot, the stories in the „Upcoming“-sprint might already have story points as they can even have come from a previously ongoing sprint. If they at some point lose their relevance, then it’s fine to put them into the backlog or simply close them.

You can see that I used the sprint goal field to clarify what the „meta“-sprint is about. This is an important part as I iterated several times about those texts and verified with each customer, if it made sense to them. I wanted to be sure that their new and old stories always went to the right place.

The „Refinement“-sprint

The next „meta“-sprint is the „Refinement“-sprint. It contains all the stories that should be done in the near future and are prepared by the PO to be filled up with details during the Scrum teams refinement meetings. In our Jira workflow these stories were in the „Requirements engineering“ step.

During those meetings the team would simply go through each story from top to bottom and make sure that each story fulfils their „Definition of ready“. Many teams estimate stories during the planning meetings, which I never liked. Getting an estimate just right before I wanted to put a story into a sprint caused a lot of stress for me. I had almost no time to react when a story got a bigger estimate than I or the stakeholder expected. And I wasn’t able to make sure that all questions which might arise during an estimation could be answered before a new sprint would start. Therefore we had two 1-hour refinement meetings during our 2-week sprints and I had enough time to discuss details or priorities with the stakeholders and split stories if necessary.
And also the team had more time to solve technical questions which might need some outside help.

When the team was done preparing a story in the refinement meeting, it would have story points and it would be marked as „Open“ in the workflow. That means it could be worked on at any time if prioritised into a sprint. This should represent the "definition of ready" in Scrum with any other requirement your process might have for stories.

The „Prioritisation“-sprint

I now had an amount of stories at the top of the „Refinement“-sprint that I could work with as PO. So I put the stories where I was sure they can be prioritised into the next „meta“-sprint called „Prioritisation“-sprint.

For some stories the stakeholder just wanted to have an estimation or understand the complexity before making a decision. Those I put into the „Upcoming“-sprint again and assigned them to the person responsible. They could then also decide to put them again into the „Prioritisation“-sprint. Which meant, we as a team could work on them according to the stakeholders / customers priority.

Having this sprint far away from the backlog keeps you usually from suddenly having a story in there which was just created or someone accidentally put there.

As we started sprints on Mondays, I always made sure that each customer showed some activity in their priority in the week before, so I knew I could rely on the list for the next sprint.

The actual sprints

At the top of the screen are the „normal“ sprints. There is the currently active sprint which shows the stories that are in progress and there is the empty sprint that will come next. This one should stay empty until one finishes the current sprint during the next planning meeting.

When finishing the current sprint any unfinished stories will move to the next sprint and stay in order. This way you can easily see which stories are unfinished and you can check whether they should go into the next sprint. Sometimes stories are actually done, but someone forgot to close them. This should rather be checked before closing the old sprint, so your metrics show those hard earned story points.

When this is done, the team can now use the little drag icon at the bottom of the sprint to move stories from the „Prioritisation“-sprint into the next sprint. The story point count will go up and the team can stop when they think they reached the amount they choose to commit to.

Here you can see the whole board with all sprints:

Other tipps & tricks

When your amount of stories grows bigger, define some filters in the board which allow you to easily spot stories which are in the wrong sprint. Having a filter that just shows stories that are not „ready“ will help you to remove them from the sprints where they don’t fit. Same for other statuses and steps on your workflow.

I spent a bit of time every month to improve my filters and my Jira dashboard to allow me to spot stories which are not in the right place as fast as possible. For example customers might create „bugs“ which should be monitored and taken care of. But when they are stressed they might put it into the wrong sprint or at the end of the backlog where nobody spots them. Or a developer injects a story into the sprint without telling anyone about it. Your dashboard should just show these kind of mishaps. It’s not about telling people they did something wrong, it’s about making sure, everyone is synchronised.

If you have a step in your workflow that can mean two things, just insert another step and remove the source of confusion.

Summary

Until recently this system felt so natural to me, that I didn’t think of writing it down. Now I feel that this might help other teams to reduce errors, confusion and to be more effective. Try it out in your Jira or set up a trial.

Every time you feel like things are mixed that should be separate, take a step away from your issue and see if you can divide it into smaller parts. Then conquer them!

If you did, I would love to know about your experience. And if you have a similar or different system that works great for you, I would also love to know more about that.

Using Telegram to monitor your Gitlab pipelines

Sebastian Helzle — Tue, 10 Dec 2019 14:58:39 +0000

How to be aware of what your pipelines are doing without wallboards and separate browser windows

As a Freelancer I often work with customers who have their own servers, but leave most of the technical work to me. I don't enjoy working directly on servers that much, so the first thing I do when a new server needs to be configured, is installing a Gitlab Runner.

Setting up pipelines

This service is then connected to Gitlab.com, the customers Gitlab instance or my own self-hosted Gitlab. Then I set up a deployment pipeline which matches to the project. So for PHP projects I usually choose TYPO3 Surf to execute actual deployments. Deployer is also an option, but I just got lately into using it more and primarily use it of other tasks. For other kinds of projects you would of course choose the tool which matches best. For Ruby projects it could be Capistrano, or you just have a bunch of Shell/Docker scripts.

After setting up a pipeline in Gitlab to automatically run builds, tests, deployments and other tasks, my project workflow is usually only based on pushing data to Gitlab. So I push via Git and then start working on the next task. Gitlab then handles the rest by communicating to the Gitlab Runner that is running on the server. The runner will then build the project, run some tests and finally deploy new releases. And the whole thing might work out or fail...

How to know what the pipeline is doing

So for quite a while I was looking for a way to monitor what happens after builds succeed or fail. I'm usually interested in any kind of failure in any stage of the pipeline, to start fixing the issue. Or success messages, when a deployment went through, after which I like to run some manual tests and inform the customer of the finished update.

Of course you can simply go to the Gitlab instance and watch the pipeline view and see what's going on. You can also setup awesome wallboards on separate screens, or have a Raspberry PI to create some interesting output. But all these things were to time consuming for me, or didn't work out if I'm working from somewhere else.

Therefore I was searching for a way to passively monitor the pipelines with the least amount of distraction. After quite some time of searching I found out that a Gitlab integration for the Telegram messenger exists. It's called Integram, is Open Source and works really well. It also supports the todo list Trello and the code management tool Bitbucket.

Using Integram

Integram basically offers a chatbot for Telegram. This bot allows you to interact via messages with your Gitlab instance. You can add hooks to the projects that should be connected and the bot will then inform you of the progress of these projects pipelines.

As Telegram offers apps for iOS, Android, Mac OS X, Windows etc.. you can receive those messages everywhere. For example, I do a git push with a new release tag, then go make a coffee in the kitchen and a few minutes later my Apple Watch notifies me that the triggered deployment when through.

If you don't trust the Integram bot, you can also host the service yourself. This way you can keep the whole CI infrastructure to yourself.

Of course you can also attach the bot to a group chat, so a whole team can be informed.

Find the information on how to set it up in their Github repository based on the integration you need. You basically setup the bot in your Telegram chat and add service hooks to your individual project repositories in Gitlab. The bot will guide you through the whole process. I didn't want to copy the whole procedure here as their readme is always up-to-date and has all the details.

One note: when you configure the service hook make sure you select all the events you need. I usually select Push Events, Tag push events, Job events and Pipeline events.

Summary

In my opinion, the Integram bot is a non-intrusive way of being informed of builds & deployments. As Telegram allows you to treat the chatbot like any other user, you can even mute it for a while if necessary.
If you or your company uses Slack, there are of course integrations which might suit you better.