Translations

[hahawoo]

I think it might be nice if love-api had translated descriptions.

Things I'm unsure of:

• How can the translated text can be automatically retrieved from the wiki? Would the scraper from SublimeLove be a useful starting point?

• What's the best way of putting the translations into the love-api table?

One option is to have a translations table next to every description:

{
    name = 'hasTextInput',
    description = 'Gets whether text input events are enabled.',
    translations = {
        de = 'Gibt zurück, ob Texteingaben-Ereignisse aktiviert sind.',
        ja = 'テキスト入力イベントが有効であるかどうか取得します。',
        ko = '텍스트 입력을 감지하고 있는지 확인합니다.'
    }
    variants = {
	{
	    returns = {
		{
		    type = 'boolean',
		    name = 'enabled',
		    description = 'Whether text input events are enabled.'
                    translatations = {
                        de = 'Ob Text-Ereignisse aktiviert sind, oder nicht.',
                        jp = 'テキスト入力イベントが有効であれば true を、無効であれば false を返します。',
                        ko = '텍스트 입력을 감지하고 있으면 true.'
                    }
		}
	    }
	}
    }
},

• Would it be useful to automatically translate (using Google Translate or something) missing descriptions? Maybe it could have tag at the end or something letting love-api users know what's automatically translated and what's not, like de = Ob Texteingabeereignisse aktiviert sind. [auto]'`

@rm-code, since you're a wiki translator I'm sure you have a much better idea about all of this stuff than me! :)

Also I just noticed now how much better the documentation could be for languages other than English... The module pages (e.g. http://www.love2d.org/wiki/love.keyboard_(Deutsch) ) only list translated functions (surely it would be better if the English version was there if the translated version was unavailable?), and the module links on the left side bar only link to English pages.

So, this all seems like a lot of work and I don't think it will/should happen necessarily, but I just wanted to post this as a "pie in the sky" feature. :)

[rm-code]

How can the translated text can be automatically retrieved from the wiki?

I haven't tried / used the scraper, but of course automatic updates would be a big improvement over our current approach.

What's the best way of putting the translations into the love-api table?

The option you mentioned probably would be the easiest to realise, but then again it would bloat the whole api table even more. It would be nice if we could move translations to seperate files / tables and just fetch the correct entry based on IDs / keys ... not sure how to approach this though.

I like the idea of translating missing pages via google translate though.

All in all I think this would be an useful addition, though it always depends on the quality (and quantity) of the translations on the actual wiki. Right now for example the german wiki is missing a lot of pages and a lot of the translated ones are pretty outdated :/

[hahawoo]

I actually don't mind the table being bloated that much, because it's not much different either way for the user of the table.

What I am thinking of though is what would make it easiest for translators if, hypothetically some time in the future, this was the primary place of documentation/translation rather than the wiki? Could this possibly provide a better translating experience?

Another reason for keeping translations in separate files might be that each file could be maintained by different people, since it would be kind of weird accepting pull requests from a language the maintainer wasn't familiar with.

One idea would be to have a table with function name keys, which contains tables with pairs of English and translated strings that this function has. This file could be checked against the main table to find any missing translations. One thing I'm not sure about though is how it could be made easy to change the main English table and then have these changes automatically or easily applied to the translated tables.

{
['love.graphics.draw'] = {

'Draws a Drawable object (an Image, Canvas, SpriteBatch, ParticleSystem, Mesh, or Video) on the screen with optional rotation, scaling and shearing. Etc...',
'Zeichnet ein zeichenbares Objekt (z.B. ein Bild) auf den Bildschirm, wobei sich Größe, Rotation und Scherung anpassen lassen. Etc...',

'drawable',
'drawable',

'A drawable object.',
'Ein zeichenbares Objekt.',

'x',
'x',

'The position to draw the object (x-axis).',
'Die Position auf der x-Achse an der das Objekt gezeichnet werden soll.',

'y',
'y',

'The position to draw the object (y-axis).',
'Die Position auf der y-Achse an der das Objekt gezeichnet werden soll.',

'r',
'r',

'Orientation (radians).',
'Die Rotation in Radianten.',

'sx',
'sx',

'Scale factor (x-axis).',
'Der Skalierungsfaktor in x-Richtung.',

'sy',
'sy',

'Scale factor (y-axis).',
'Der Skalierungsfaktor in y-Richtung.',

'ox',
'ox',

'Origin offset (x-axis).',
'Verschiebung vom Urpsrung auf der x-Achse.',

'oy',
'oy',

'Origin offset (y-axis).',
'Verschiebung vom Urpsrung auf der y-Achse.',

'kx',
'kx',

'Shearing factor (x-axis).',
'Der Scherfaktor in x-Richtung.',

'ky',
'ky',

'Shearing factor (y-axis).',
'Der Scherfaktor in y-Richtung.',

'quad',
'quad',

'The Quad to draw on screen.',
'Das Quad welches gezeichnet werden soll.',
}
}

[hahawoo]

This isn't perfect to say the very least, but, here is a start of some translations!

https://github.com/love2d-community/love-api/blob/gh-pages/test/api.lua
http://love2d-community.github.io/love-api/test/de.html
http://love2d-community.github.io/love-api/test/ja.html
http://love2d-community.github.io/love-api/test/ko.html
http://love2d-community.github.io/love-api/test/pt.html
http://love2d-community.github.io/love-api/test/ru.html

I've also added the mini-translations as seen on the module/type pages on the wiki, because I figure this would be especially useful for languages other than English; instead of just reading function names in the navigation, there's a little translated description too.

The code which generates the translations is a mess. Basically what happens is:

• The LOVE API is looped through and links are generated for the the export versions of each function/type/enum, e.g.: https://www.love2d.org/wiki/Special:Export/love.math.random_(%E6%97%A5%E6%9C%AC%E8%AA%9E) and they are all downloaded (I used aria2 for this).
• These files are parsed and the descriptions are added to the API table.
• For the automatic translations, a text file is generated containing each English description and an ID number, and the "keywords" (names of LOVE functions/types/enums) in the description are replaced by ID numbers.
• The text file is automatically translated, the "keyword" numbers are replaced by the actual keywords, and each missing translation in the API table uses the automatic translation.

I managed to mess this up pretty badly, especially the automatic translations, but hey, it's a start. :P

[hahawoo]

I've moved this for the time being to: https://github.com/santoslove/love-api-experiments/