inkle / inkle/inky

Localization (multi-language) support thoughts

Open
#218 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
2.7k
Forks
340
PR merge metrics
No merged PRs in 30d

Description

Hello everybody,

I've been trying to work on a localization system that works with Inky and Ink compiler and I have some interesting conclusions.

First of all, I've not accomplished what I wanted. I'm not used to programming with Javascript, I don't know about the code of Ace editor (the base of Inky) and I am not the creator of Inky and Ink compiler (and they are relatively complex). In any case, **my conclusions may be useful for Inkle programmers**, let's see.

Basic principles
- All texts need a GUID (a Globally Unique Identifier)
- That means that all ink files will have some extra rows at the end of the document to write these GUIDs
- GUIDs order match with texts order
- Inky needs to save an extra file (a CSV to be able to translate texts in a spritesheet (commonly used) app) with all GUID and texts paired.
- Inky needs to read from that CSV file on export to JSON to make every text something like that: "^Default language text^Texto en idioma por defecto^Text en l'idioma per defecte", that is every text with all languages.
- Ink implementation has to split texts by "^" character (or whatever character or string used) and use the one of the language set.

Let's see some examples:
- Simplest example, 1 file, 2 texts:
![image](https://user-images.githubusercontent.com/9904952/71260475-41129180-233b-11ea-84f4-60c488901d6b.png)
![image](https://user-images.githubusercontent.com/9904952/71260488-4a9bf980-233b-11ea-83ef-11c8c87b42cf.png)
- Now, with 2 files (new text is inserted at the end of the CSV file):
![image](https://user-images.githubusercontent.com/9904952/71260638-a1a1ce80-233b-11ea-9376-5e131b90f7f7.png)
![image](https://user-images.githubusercontent.com/9904952/71260655-a9617300-233b-11ea-9732-faa9626dba1a.png)
- Now, I have inserted a text between 2 first texts (GUID in ink file is inserted at place, but on CSV is inserted at the end of the file):
![image](https://user-images.githubusercontent.com/9904952/71260689-c26a2400-233b-11ea-8145-617950650ce4.png)
- If a line is deleted, its GUID is deleted on ink file and CSV:
![image](https://user-images.githubusercontent.com/9904952/71260775-fe9d8480-233b-11ea-8587-e4da35c738ec.png)
- And if another is written another GUID is generated:
![image](https://user-images.githubusercontent.com/9904952/71260810-1412ae80-233c-11ea-9f88-5a2b0baf1af1.png)

**Now some technical thoughts.**
About GUIDs on ink files:
Create a GUID per line and place it on the bottom of an Ink file is easy, place it between other GUIDs depending on the order of the line referenced is easy too.
I've done that inside "if statement" of Line 12410 (if (session.getDocument().isNewLine(text))) in ace.js file.

But we need to have GUIDs per texts, a logic line is not interesting and shouldn't generate a GUID, a line with text, logic and text should generate 2 consecutive GUIDs. I didn't accomplish that and it is the "game changer".

About CSV:
When saving Ink project, Inky must save a CSV file with all GUIDs as said but it is important to not destroy previously translated texts so:
- First, create a dictionary or map with all GUIDs -> texts of ink files
- Then create an array of bools with the same size of the dictionary
- Then compare CSV GUIDs with the dictionary (if it is not found, delete the CSV row and if it is found mark as true the position on the bool array)
- After that, loop over dictionary and if hasn't been found on the CSV (bool array is for that) add it as a new row on the CSV

Hope it will help to enhance Ink and Inky.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.