Multi-language teams

[N1cky94]

Hi

I work in a multi language team where the devs are english speaking. But the domain (business) speaks mainly dutch.
Would it be an idea to add a feature where we can also add aliasses that we define in different languages.
e.g.:

contexts:
   - name: Library
     domainVisionStatement: A great place to find books
     terms:
        - name: Library
          definition: a great place to find and read books
          aliases:
             - Public Book Collection
          translations:
             - NL Bibliotheek
             - FR Bibliothèque
             - DE Bibliothek

This might make sure that when we work with multi-language teams, all languages are covered as well.

[chrissimon-au]

Hi @N1cky94 ,

Thanks for sharing this - multi-language support has been on my mind, but there are a range of scenarios that could be helpful - can you clarify the scenarios that this would be useful for you?

You mentioned that the developers are speaking English and the domain experts are speaking Dutch - but what language are the domain models in? For example:

1. Domain models in code are in Dutch, English-speaking developer needs the English definition, e.g. public class Bibliotheek() with hover panel showing Library: a great place to find and read books.
2. Domain models are in English, but Dutch-speaking domain experts are doing domain modelling (e.g. event storming) in Dutch and developers need guidance as to what English words to use in the code
3. Domain models are in a mix of English and Dutch, domain experts and developers both need the definition in their languages whatever the codebase is in?
4. You want to export your definitions to a wiki, for example, and want all the translations shown?

In terms of option 1, this would work right now with the aliases feature, e.g.:

contexts:
   - name: Library
     domainVisionStatement: A great place to find books
     terms:
        - name: Library
          definition: a great place to find and read books
          aliases:
             - Public Book Collection
             - Bibliotheek
             - Bibliothèque
             - Bibliothek

If the code had public class Bibliotheek() then the hover panel would show Library: a great place to find and read books as well as all the aliases.

For option 3, we would also need to store the definition and domain vision statement in other languages. Option 2 and 4 might also require other support in the definitions file and in the functionality.

Look forward to your thoughts and preferences!

[N1cky94]

Hi @chrissimon-au

Thank you for your quick reply.

We are more in Option 2 with some Option 3 situations.
Our developers and code base use the English language exclusively. But the domain is always described and discussed in dutch and sometimes french, with our customers. We have had issues where different translations were used for dutch words or definitions. Leading to confusion during reviews. We also have a lot of words in dutch that look english, but mean something else. We have had some funny scenario's with that.

We also use the definitions file as a communication file with our customers. That so far has been a great success. I then translate the file manually to English for the developers to use. Which gives us a clear domain description. I now add all dutch words as aliases. But we want a clearer seperation of aliasses vs dutch words.

I would like the definitions and accepted aliases within the code to be set as English. So it helps our developers.
But it also provides the dutch words being used for those concepts, so we know what dutch words map to what English domain words. This will also help in the communication with our customers. So they know how their words are perceived by us.
If we can add both English and dutch definitions, that would be awesome, as this will clear the gap between domain and developer even further.

We love the tool, and that's why I want to suggest this possibility.

Kind regards
Nick

[chrissimon-au]

Thanks @N1cky94 that is helpful context. A few followup questions:

Configuration Approach

Before proceeding, it's worth being aware of a planned change to the configuration file approach outlined here - tldr; separate file per context, located in the folder hierarchy close to the context code files. Given the size of these changes, I will likely approach that change first, and then introduce multi-language.

Once we have a file per context, my suggested configuration schema is as follows:

If you only needed a single language you could keep it simple with something like:

name: Library
domainVisionStatement: A great place to find books
terms:
   - name: Library
     definition: a great place to find and read books
     aliases:
        - Public Book Collection

But if you need multi-language, then each 'block' could be replaced by a dictionary of language keys, e.g.

en:
   name: Library
   domainVisionStatement: A great place to find books.
nl:
   name: Bibliotheek
   domainVisionStatement: Een geweldige plek om boeken te vinden.
terms:
   - en:
       name: Library
       definition: a great place to find and read books
       aliases:
         - Public Book Collection
     nl:
       name: Bibliotheek
       definition: Een geweldige plek om boeken te vinden en te lezen.
   - en:
       name: Book
       definition: A published piece of writing.
       examples:
         - "Did you read that great book I suggested?"
     nl:
       name: Boek
       definition: Een gepubliceerd stuk tekst.
       examples:
         - "Heb je dat geweldige boek gelezen dat ik je aanraadde?"

Effectively the terms key is an array and each element of the array is a dictionary keyed by language. This means each term can be defined in 1 or more languages.

This keeps it close when updating the definition, examples and name in a given language, but also not hard to see if the definitions and terms are diverging between languages.

I did consider other approaches, such as a file per language, or a top level block per language, but this separated the term definitions too far away and made me worry that folk might add words into a language and miss the other languages, or update a definition in one language and miss that they need to update it in another.

The tradeoff here is that adding a new language would require inserting a new language block into each term - but we could build some helper tooling to add a new language which would insert placeholder blocks for the new language into each term block.

Behaviour

I'm considering the following behaviour - does it make sense?

1. Hover:
   • Contextive would find any word from any language and show the definition in the user's configured language, either defaulting to their OS culture, or with an explicit override setting. e.g.
     • if your culture was EN (default or configured), then class Library and class Bibliotheek would both show in the hover panel Library: A great place to find and read books.
   • should it show other languages at the same time? Perhaps a config setting that allows to choose multiple languages to show? e.g.
     • if your config said to 'show me EN and NL' then class Library and class Bibliotheek would both show in the hover panel Library: A great place to find and read books AND Bibliotheek: Een geweldige plek om boeken te vinden en te lezen.
2. Auto-complete
   • Contextive would default show only the options from your default (or configured language)
   • If we support a config setting to show multiple languages, we should show words from multiple languages in the autocomplete list
     • should this be the same setting as for hover or different? i.e. given your context, would it make sense to say "we only want to write code in English, but want definitions shown in English and Dutch"

Look forward to your thoughts!

[N1cky94]

Hi @chrissimon-au

It took me a while to get back to this.

Configuration

This looks easy and simple to me. So this is something that would work for us.
Tooling might be useful, but for is it's great that everything is kept together. And with the - context seperation - update, these documents are kept small and manageable.

Behaviour

Hover

I like the idea. But maybe we can configure that you can choose not only the language it shows you everything in. But also configure of what language it should just show you the dutch words that business is using. E.g.:
`Library: A great place to find and read books (Dutch: Bibliotheek)

This way, if we need to start a discussion with business or vice versa, we can see the correct words within the code base via hovering.

Completion

For my context, the definitions for my developers should be shown in English, yet be provided in three languages in the definitions file. Translations to dutch and French (only of the words, not the definitions) should be shown. The completion should be purely kept English.

We could maybe configure this with extra options, so this might work for all kinds of use cases, e.g.:

language:
   - eng: default
   - nl: translate
   - fr: none

Where:

indicator	meaning
default	Is shown in hover and used for completion (Only one can be default)
completion	Is not shown in hover but used for completion
hover	Is shown on hover but not used for completion
translate	like hover but only the words, no definitions
none	Is not shown on hover and not used for completion

This is only a quick view on the idea, but I hope this helps.

Kind regards
Nick

[hinogi]

maybe you could work together with these guys
https://github.com/lokalise/i18n-ally

[N1cky94]

@hinogi
That looks great, but for me it's not in the code itself, it's to help my team.
But a combination of this with Contextive, that would be awesome.

[sdavids]

#95 (comment)
#95 (comment)