Flatten translations

[asvae]

Currently in translations we have nested collection.

That's not ideal because:

• it's hard to merge
• it's hard to support multiple translations
• it's tricky to manage "general" translations

Instead we can try flat collection.

Here's an example of flat collection:

{
  "landing_header_buttons_overview": "Overview"
}

Implementation

introduce a script that

• [ ] converts current translation strings to flat collection
• [ ] converts flat collection to current translation string (so we can roll it back if needed)
• [ ] updates translation strings accordingly (assume all translation strings are fully exposed in the code. I.e. always some.translation, never some.${translation}).

You can use yargs to introduce arguments, but generally we want this script to "somehow work", as it's probably going to be used once, then forgotten. So speedrunning this task would make the most sense.

Bonus points

• see https://github.com/epicmaxco/vuestic-ui/issues/648, you may want to handle this issue as well.

[m0ksem]

{ "landing_header_buttons_overview": "Overview" }

We can use dots instead of underlines which is easier to copy & paste.

{
  "landing.header.buttons.overview": "Overview"
}

$t('landing.header.buttons.overview')

[asvae]

@m0ksem pretty sure it'll break vue i18n (it will try to resolve nested). how exactly are dots easier to copy?

[mxmvshnvsk]

After translating the documentation into Russian, I can highlight the following cons of flatten structure:

• nested structure is convenient for navigating through the file, for example, you can collapse blocks that you are not working with at the moment
• file search is more intuitive, flat structure will make you think of names to search
• naming will not be very simple
• dynamically updating the file will be more difficult (for example, when adding a new language, automatically adding fields for translations #911)

In general, refactoring is necessary for locales, but you might consider post-generation of a flat locale file, for example, collapse the path into a string (key).

For example:

// Convenient navigation, clear structure
{
  "shared": {
    "overview": "Overview",
    "description": "Description",
    "notification": {
      "success": "Success notification",
      "error": "Error notification"
    }
  },
  "someModule": {
    "name": "Some module name"
  }
}

// Flatten structure, difficult to search option
// You will need to keep the key pattern in mind
{
  "shared_overview": "Overview",
  "shared_description": "Description",
  "shared_notification_success": "Success notification",
  "shared_notification_error": "Error notification",
  "someModule_name": "Some module name"
}

A non-object approach is not intuitive for developers, therefore, describing translations of documentation will be annoying.

[asvae]

Hmm. Fair point. I guess we can just add:

• Sorting on pre-commit.
• Script to check for unused translations.
• Translations sync script.

And call it a day.

[mxmvshnvsk]

@m0ksem dot-separator difficult to understanding, because it means object path. _ and word divided by _ supported double click, it's better for Ctrl+C -> Ctrl+V =)

[mxmvshnvsk]

@asvae I can do this, anyway the next task is about locales.

[asvae]

@mxmvshnvsk sure, thanks.

Won't be able to update this issue today, but feel free to ping me in discord. :)

[m0ksem]

How about making a simpler file structure?

- locale
- pages
  - examples
    - example.vue
    - ...
  - page-config.ts
  - page.vue

In this case, we can add the locale files to the page. Then merge it into one global locale. This will be more complex, but we will have fewer larger locale files. I'm not sure we really need this, but it's an idea.

- locale
  // Global locales like vmodel, input, value etc.
  - en.json
  - ru.json
  - es.json
- pages
  - locale
    - en.js
    - ru.js
    - es.js 
  - examples
    - example.vue
    - ...
  - page-config.ts
  - page.vue

[asvae]

@m0ksem I would leave one file for now, just for ease-of-support.

We might make more translation files when docs grow up as we'd need to lazy load translations most likely.