Home

Welcome to the MrMeeseeks.ResXTranslationCombinator wiki!

Requirements

• ResX default file (see Definitions)
  • Where values are of a language of your choice, which DeepL supports
• An auth key for the DeepL API (you'll need an account for that)

Definitions

The ResX file family definition:

	default file	automatic file	override file	combined file
description	Defines keys which should be included in all other ResX files. And its values are used for the automatic translations.	Its values are the automatic machine translations of the default file's values with the same key using the target language defined by the [languageCode].	It is optional (if existent it will be considered). Meant for language experts or linguist to override automatic translations if necessary.	Values take the value from the override file (if the override file exists and has an non-empty value for the corresponding key) or fallback to the value from the automatic file.
naming pattern	[name].resx	[name].[languageCode].a.resx	[name].[languageCode].o.resx	[name].[languageCode].resx
created/edited by	you/developer	MrMeeseeks.ResXTranslationCombinator	you/language expert	MrMeeseeks.ResXTranslationCombinator

How does it work?

The Github Action of this project searches for default ResX files. Following steps are executed per default file:

1. the already existing automatic and override files are collected
2. missing values in automatic files are filled by automatic translations of the corresponding value in default file using the translation provider
3. automatic and override files are combined into combined files. Prioticing the override value (if existent) or else falling back to the automatic value.
4. An empty template file for overrides is created

Inputs & outputs of the github action

inputs:
  dir:
    description: 'The root directory to work from. Example, "path/to/code".'
    required: false
    default: '.'
  auth:
    description: 'Auth key for your DeepL API access.'
    required: true
  excludes-regex:
    description: 'Regex for names of default ResX files in order to decide whether to exclude file from processing.'
    required: false
    default: ''
  data-copies-regex:
    description: 'Regex for names of default ResX files whose data should be copied instead of translated.'
    required: false
    default: ''
  filter-keys-with-overrides:
    description: 'If set the default keys are filtered by the super set of override keys per ResX file family.'
    required: false
    default: 'false'
outputs:
  summary-title:
    description: 'The title of the commit for the pull request.'
  summary-details:
    description: 'The summary details of the commit for the pull request.'

Sample workflow

It is adviced to use this step in combination with a step which creates a pull request from the changes. Then the changes during the combination step will be commited and a pull requested.

name: Create translation pull request

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only if resx files where involved
on:
  push:
    paths:
    - '**.resx'

# GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow.
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@main

      # Translate and combine ResX files
      - name: Translation and Combination
        id: translator
        uses: Yeah69/MrMeeseeks.ResXTranslationCombinator@main
        with:
          # The authentication key of the DeepL API access
          auth: ${{ secrets.DEEPL_API_AUTH_KEY }}

      - name: create-pull-request
        uses: peter-evans/create-pull-request@main
        with:
          title: '${{ steps.translator.outputs.summary-title }}'
          commit-message: '${{ steps.translator.outputs.summary-details }}'

This workflow triggers the translation combination action whenever a commit got pushed onto the repository, which contained changes in ResX files. The sole input parameter which needs to be set up is the DeepL API authentication key. You should do that as a secret, see https://docs.github.com/en/actions/reference/encrypted-secrets. The last step creates a pull request which contains all the changes from the combination action.

Samples

Initial creation of default file

Initially you would only need to create a default file and fill it with the initial keys and the corresponding values in a language (supported by DeepL) of your choice. The result will look like that (for brevity only English and German are shown):

Notice that a template file for override files is automatically generated. Which we'll use in the next step.

Overriding values

You won't even have to copy & paste the template file. Just rename the "template" part to the language code which you want to override. A new template file will be generated with the following step. For brevity only the relevant changes are shown:

What will happen if we add some keys?

Adding new keys

New additions won't bloat the diff of the pull request which'll be as big as the following diagram shows (besides the omitted languages of course):

Same goes for deletions which won't be documented here.

Overriding unsupported languages

You can also override a language which isn't supported by the translation provider (in this case of this project DeepL) at all. However, then all values have to be translated manually in the override file:

Note that there is no automatic file this time. If some of the values are left out, the combined file will still be created, but the values will be left blank.

Sample project

If you want to see this project (and another one; https://github.com/Yeah69/MrMeeseeks.ResXToViewModelGenerator) in action in a full sample project have a look into: https://github.com/Yeah69/MrMeeseeks.ResXLocalizationSample

Remarks

• The set of the combined files (and the default file) are intended to be used as the localization for your application.
• The override and automatic files shouldn't be relevant to your application directly.
• The automatic files work like translation caches. Only their missing values are going to be translated.
  • That means if you would like to have a specific value re-translated then just remove that value. If you would like to have the whole localization for a specific language translated, delete the corresponding automatic file.
• Overriding the automatic translation is designed to be completely on demand. It's great if it isn't necessary. However, if it is still needed point-wise, you have the ability to override precisely.
  • However, if you want to override an unsupported language, you'll need to manually fill all values
• Upon generation of the automatic, override and combine files the keys are sorted alphabetically. This'll reduce the diffs of the pull request to the relevant parts only! It'll also prevent unnecessary pull request (nothing changes in resx files) at all!