Unofficial Vortex Translation Tool
===================================

Version: 1.0.12 (Compatible with Vortex v1.2.15 to v1.2.20)
Author: BowmoreLover
Distribution page: https://www.nexusmods.com/site/mods/33
Last updated: Jun 09, 2020 (UTC)

Updater for Vortex 1.3.5 (Sep 10, 2020 (UTC)):
Now available an updater for Vortex 1.3.5 to 1.3.8 on update files section. Just overwrite the updater after installing VortexTrnsTool 1.0.12.


===================================================================================================================
CONTENTS

1. Introduction
2. Motivation and purpose
3. Requirements
4. Install
5. Uninstall
6. Step-by-step tutorial
   Step 1. Extact translation text from Vortex sorce code
   Step 2. Merge Json files
   Step 3. Convert Json to Mcm
   Step 4. Translate Mcm
   Step 5. Convert Mcm to Json
   Step 6. Deployment / Distribute the translated Json files
7. Notes / Limitation / Known issues
8. Credits & Special thanks
===================================================================================================================


===============================
 1. Introduction
===============================

This is a tool to help Vortex translators.
- You can extract translation text from Vortex source code as a translation source.
- You can convert Json to/from Mcm(*) file, so translate it easily using such as xTranslator instead of directly editing Json.
- You can use almost complete English Json files as a translation source.

(*) The file format used in the Mods menu of Skyrim/Skyrim SE (also used in Skyrim/FO vanilla game UI).



About Vortex translation, see Tannin's forum post: Translating Vortex


===============================
 2. Motivation and purpose
===============================

The current Vortex translation work has the following problem:
- Vortex can translate UI using Json file, but only a small amount of English text to translate is provided. So need to collect English text while manipulating the screen with translation helper extension. Not only is it difficult to cover all of the translated text, it is also need to collect every version update.
- It is troublesome to directly edit the Json file, and it is necessary to write it so as not to break Json's syntax, so everyone can not easily translate it.

I am willing to translate Vortex into my native language and contribute to the project, but I don't want to do troublesome and unnecessary work. So I decided to make this.


===============================
 3. Requirements
===============================

- Windows 7 or later (Tested on Windows 10)
- Microsoft .NET Framework 4.6.1 or later
- Vortex 0.16.10 or later

(Recommended) TES/FO Translation Tool
- xTranslater by McGuffin
  Other tools may be able to translate, but I only tested this.

(Optional) For extracting English Json file from Vortex source code:
- Vortex source code (GitHub)
- Any git client. I'm using as below:
  git for windows
  TortoiseGit

(Optional) For collecting missing translated text of this tool:
- Translation Helper 0.0.5 or later


===============================
 4. Install
===============================

Download archive file and extract to any folder.
Must be sure not install to Windows/Program Files/Games/Vortex installation folder.

Notes on updating:
When overwriting the Workspace folder, be careful not to lose your modified files. If you do not do extraction from source code or merge jsons but just translate using merged json or Mcm text, you can overwrite it. However, if not, simply overwriting may cause your modifications to be lost.


===============================
 5. UnInstall
===============================

- Delete the installed files and folders.
- Delete "%LOCALAPPDATA%\VortexTrnsTool" folder (Configuration file will be here).
  Depending on your PC, for example: C:\Users\BowmoreLover\AppData\Local\VortexTrnsTool


===============================
 6. Step-by-step tutorial
===============================

The figure below is a translation workflow using this tool. The tool is set by default according to this flow.



In the explanation Workspace is the "Workspace" folder created in the installation location of this tool. By default, all files required for work are placed in this folder (and subfolders).


"Workspace" folder structure:

<Installation location>/
   + Workspace/
      + (a)Extracted/ --- Json extracted from source code will be created here.
      + (b)Additional/ --- You can place Json files that contains additional translation text.
      + (c)Captured/ --- You can place Json files that captured by translation helper extension.
      + (d)Merged/ --- Json merged from (a)+(b)+(c) will be created here.
      + (e)Mcm/ --- Mcm converted from (d) will be created here.
      + (f)Translated/ --- Json converted from Mcm will be created here.
      + Translation Installer/ --- Simple installer for translation.


This tool contains the results file that ran through Step 3 using the latest Vortex source. So you can do only the last translation work from step 4, or you can use just the English Json files in "Workspace/(d)Merged" folder.

Q: Anyway I would like to use the latest English Json. where is it?
A: See "Workspace/(d)Merged/" folder.

Q: I would like to translate using the latest English Json and xTranslator. what should I do?
A: As follows:
  - Open "Workspace/(e)Mcm/*_en.txt" with xTranslator, translate it, and output the translated Mcm (eg. common_fr.txt) to the same folder.
  - Start the tool, open the "Mcm to Json" page, enter the language name (eg. fr) and press the "Convert" button.
  - The translated Json will be created in "Workspace/(f)Translated/" folder.


Step 1. Extact translation text from Vortex sorce code
========================================================

First, clone Vortex source code to local disk in any way.
The way to clone using TortoiseGit is as follows:
- Right-click on any Windows folder and select "Git clone" menu.
- Set as follows:
  URL: https://github.com/Nexus-Mods/Vortex.git
  Directory: Any folder of the clone destination (eg C:\Repo\Vortex)
  Depth: Checked, 1
  Recursive: Checked
  (Optional) Branch: You can specify source branches / tags as needed (e.g.: v0.16.15).
- Then press the OK button.
- Wait a few minutes for the clone to finish.

Next, extract translation text from source code.
- Launch VortexTrnsTool.exe and open "Extact from Source" tab.
- Vortex Source Top Folder: enter the top level folder of the source you just cloned.
- Extra Source Folders: You can specify extra source folders such as the other extensions.
- Press "Extract from Source" button.
- Json files containing the extracted translation text will be created in "Workspace/(a)Extracted" folder.


Step 2. Merge Json files
==========================

To complement the shortage of the translated text of the extracted Json file, merge the following Json files:
- "Workspace/(b)Additional" folder: Json files containing additional translation text manually created.
- "Workspace/(c)Captured" folder: Json files collected using translation helper extension.

The way to merge Json files is as follows:
- Launch VortexTrnsTool.exe and open "Extact from Source" tab.
- "Merge Source Folders": The proper folders are set by default. Change or add it as necessary.
- Press "Merge Json Files" button.
- Merged Json files will be created in "Workspace/(d)Merged" folder.


Step 3. Convert Json to Mcm
=============================

Convert Json file to Mcm file as follows:
- Launch VortexTrnsTool.exe and open "Json to Mcm" tab.
- "Json Input Folder": The proper folder is set by default. When changing, be sure to specify a folder with English Json.
- "Translated Json Folder": If you have a Json file that you previously translated manually, specify that folder. (*)
- "Mcm Output Folder": The proper folder is set by default.
- "Mcm language" : Switches the language in the Mcm file name. You can leave the default.
- Press "Convert" button.
- Mcm files (and optional xml files) will be created in "Workspace/(e)Mcm" folder.

(*) Basically xTranslater requires English Mcm for translation, so this tool will create English Mcm and you will need to redo the translation. If you specify Json you translated here, translation xml files will be generated and by importing this xml with xTranslator you can save time of re-translation.


Step 4. Translate Mcm
========================

If xTranslator is the first time, let's install and set up as follows:
- Download the latest xTranslator from here: xTranslator ( sseTranslator - fallout4Translator - tesvTranslator )
- Extract zip file to any folder.
- Launch xTranslator.exe
- A game selection dialog will appear. Choose Fallout 4.
- Options and Languages dialog will appear.
  - On the Options tab, select the language of the UI (will restarted).
  - On the Dictionaries and languages tab, select Destination Language.
    If language you want to translate is not listed, select any language other than en (eg. fr).
  - Creating a dictionary is optional. If Fallout 4 is installed, creates a dictionary according to the instruction of UI.
  - Finally press the OK button.
- Setup is now complete.

Next, translate Mcm files using xTranslator:
- Open "Workspace/(e)Mcm" folder.
- Drag and drop *_en.json files to xTranslator.
- A red line indicates untranslated text. Double-click each line to translate.
- Please refer to xTranslator Help and Tutorial for detailed operation.

If you created translation xml in step 2, you can import here to translate:
- Select "File - Import translation - XML files (xTranslator)" menu,
- Select xml corresponding to Mcm you are translating now (If common_en.txt select common_en_translation.xml).
- XML Import dialog will appear. Shoose "Everything" and "Use Relax FormID + Strings", the press "OK" button.
- A part of the line will be translated and change into white.

When translation is over, save the translated Mcm file:
- Select "File - Save SSTString dictionary" menu. Translation dictionary is useful for reuse of translated text.
- Select "File - Finalize MCM/Translate" menu. A confirmation message appears, so press "Yes" button.
- Translated Mcm file (eg. common_fr.txt) will be created in "Workspace/(e)Mcm" folder.


Step 5. Convert Mcm to Json
=============================

Convert translated Mcm file to Json file as follows:
- Launch VortexTrnsTool.exe and open "Mcm to Json" tab.
- "Mcm Input Folder": The proper folder is set by default.
- "Mcm language" : Enter the language of Mcm created with xTranslator.
- "Json Output Folder": The proper folder is set by default.
- Press "Convert" button.
- Translated Json files will be created in "Workspace/(f)Translated" folder.


Step 6. Deployment / Distribute the translation files
=======================================================

Deploy the JSON files created in step 5 into the Vortex folder.
- Launch VortexTrnsTool.exe and open "Deployment" tab.
- "Translated Json Folder": The proper folder is set by default.
- Language: Choose the language of translated Json.
- Check the deployment destination.
  To deploy and test on Vortex installed on PC, check "Application Data" and "Common Application Data".
  To deploy the files to the installer's folder for distribution, check "Custom Folder" and enter destinationi folder.
- Press "Deploy" button.

Once you launch Vortex and open "Settings - Interface", new language will be listed in the Language dropdown menu.

(*) "Workspace/Translation Installer" folder contains the installer batch file for the translation. You can deploy to this folder, compress folder to zip, and publish it to Nexus Mods etc.


========================================
 7. Notes / Limitation / Known issues
========================================

- In source analysis, since only regular expressions are used without using parser-combinator, extraction accuracy is not very good. However, more than 90% of the text should be extracted.

- Even if you follow the instructions in this tool, some of the UI may not be translated. Probably because all of the sources are not localized, it will be improved in future updates of Vortex.

- Perhaps such usage of xTranslator is unintended by McGuffin, please do not trouble the author of xTranslator McGuffin with issues with this tool.


========================================
 8. Credits
========================================

Unofficial Vortex Translation Tool
  Copyright(c) 2018-2020 BowmoreLover
  This program released under GPL-3 License.

This program contains the following software resources (specifically translation Json files and information of source code such as function name):
- Vortex (GPL-3 License)
  Copyright (c) 2020 Black Tree Gaming Ltd.

Third party libraries:
- Json.Net (MIT License)
  Copyright (c) 2007 James Newton-King

Special thanks:
- Tannin, Robin and Nexus Mods staff, Thank you for focusing on developing bland new Mod Manager.
- McGuffin, author of xTranslator, Thank you for sharing excellent translation tool.

Development tools:
- Microsoft Visual C# 2015 + .NET Framework 4.6.1
- git for windows
- TortoiseGit
- GIMP2
- LibreOffice

//