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

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/DeepL) 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 DeepL API
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

Sample workflow

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@v2

      # Translate and combine ResX files
      - name: Translation and Combination
        id: translator
        uses: Yeah69/MrMeeseeks.ResXTranslationCombinator@v69.0.1
        with:
          # Take root directory of the repository as directory to search for the ResX files
          dir: ${{ './' }}
          # The authentication key of the DeepL API access
          auth: ${{ secrets.DEEPL_API_AUTH_KEY }}

      - name: create-pull-request
        uses: peter-evans/create-pull-request@v3.9.2
        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.

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.