On how OXP authors (if you're among them - read it!) can help localizability

[Simba]

Krager is now translating various OXPs into Russian. The problem is that he does it by creating his own localized versions, which leads to the impossibility of rapid updates in case of new versions and leads to conflicts due to violation of the order of loading addons.

I decided to try a different approach: specialized OXP, which will contain only localization for already installed original extensions. As I assumed, this would require only redefining certain strings through plist-files, maybe changing values of some js-properties through a script, or some other simple manipulations in the code. Alas, this is not the case. In most cases it is necessary to redefine entire methods through a script, because of which in case of release of a new version of localizable OXP something may certainly break.

Here is an example of my attempt to localize Library OXP (available here https://disk.yandex.ru/d/3IrvCRoQJ5h-Sg). This example is also interesting because one of the scripts collects a string in which the value from the argument of the playerCompletedContract method is substituted, which is just a string constant and is not localized anywhere. Because of this, we had to not only redefine the method, but also make appropriate changes to its logic.

In view of the above, there are some wishes for addon authors:
1) Avoid declaring strings inside methods;
2) If such strings are not some changeable values, then they should be stored in missiontext.plist or descriptions.plist, and in the code to get them by functions like expandMissionText();
3) If there are strings in which some values should be substituted, then they should also be stored in *.plist, and the values should be substituted using [such_constructions] and the same functions;
4) If in your code the string is collected gradually or entirely consists of some non-localizable values (i.e. if they are not specified explicitly in the script, for example, names of ships or goods), it should still be placed in *.plist and collected only by substitution through functions like expandMissionText. This is necessary because localization may require changing the order of such values, adding punctuation marks or suffixes/prefixes;
5) Avoid substitution of string values that cannot be localized (example above with playerCompletedContract).

Therefore, I ask all addon developers to check their OXPs and make appropriate changes.

Before creating the topic, I wanted to make a list of addons that have problems with localization, but after looking through a hundred, I found about 50 problematic ones. I decided not to continue - apparently, about half of all addons are problematic. Here are the ones that I managed to highlight:
cim.gsagostinho.systemfeatures.rings
oolite.oxp.aegidian.LongWayRound
oolite.oxp.Alnivel.RoutePlanner
oolite.oxp.AndreyBelov.BountyInformer
oolite.oxp.AndreyBelov.DuplexFuelTank
oolite.oxp.AndreyBelov.Targeter
oolite.oxp.ArexackHeretic.CargoWreck
oolite.oxp.astrobe.spacecrowds
oolite.oxp.captain_beatnik.Riredi
oolite.oxp.CaptMurphy.BreakableTorusDrive
oolite.oxp.CaptMurphy.BreakableHUDIFFScanner
oolite.oxp.CaptMurphy.EscortContracts
oolite.oxp.CaptMurphy.PoliceIFFScanner
oolite.oxp.CaptMurphy.ShipStorageHelper
oolite.oxp.captsolo.tori2.02
oolite.oxp.capt_murphy.Illegal_Goods_Tweak
oolite.oxp.Cholmondely.Hints
oolite.oxp.cim.combat-simulator
oolite.oxp.cim.cotbs
oolite.oxp.cim.new-cargoes
oolite.oxp.cim.ships-library
oolite.oxp.cim.systemfeatures.sunspots
oolite.oxp.CmdCheyd.DH_AdvancedNavigationComputer
oolite.oxp.CmdCheyd.DH_EmergencyWitchspaceInitiator
oolite.oxp.CmdrWombat.Deposed
oolite.oxp.cody.green-gecko-xl
oolite.oxp.Commander_McLane.Anarchies
oolite.oxp.Commander_McLane.Auto_Eject
oolite.oxp.Commander_McLane.Cataclysm
oolite.oxp.Commander_McLane.Interstellar_Help
oolite.oxp.Commander_McLane.Randomshipnames
oolite.oxp.Commander_McLane.Wormhole_Restoration
oolite.oxp.CommonSenseOTB.ShieldEqualizer+Capacitors
oolite.oxp.Day.Diplomacy
oolite.oxp.Diagoras.MiningContracts
oolite.oxp.Disembodied.FreeTradeZone
oolite.oxp.Draco_Caeles.GenerationShips
oolite.oxp.DrewWagar.TianvePulsar
oolite.oxp.DrNil.YAH
oolite.oxp.DrTripsa.InSystemTrader
oolite.oxp.EricWalch.DeepSpaceDredger
oolite.oxp.EricWalch.DeepSpacePirates
oolite.oxp.EricWalch.MisjumpAnalyser
oolite.oxp.EricWalch.TionislaReporter
oolite.oxp.Frame.FuelCollector
oolite.oxp.IronFist.Draven
oolite.oxp.JohnSmith.LoveCats
oolite.oxp.Killer_Wolf.Adder_Mark_III
oolite.oxp.Layne.DockingFees
oolite.oxp.LittleBear.AsteroidStorm
oolite.oxp.littlebear.blackmonks
oolite.oxp.LittleBear.GalacticAlmanac

[Cholmondely]

This dumb pilot would love to help - anything to help those extending Oolite to others. But, as a dumb pilot, I totally fail to understand how I can help you.

1) I don't know what a string is. I don't know what a method is.
2) I don't know what a changeable value, a function or expandMissionText() are.
et cetera.

[phkb]

This dumb pilot would love to help - anything to help those extending Oolite to others. But, as a dumb pilot, I totally fail to understand how I can help you.

1) I don't know what a string is. I don't know what a method is.
2) I don't know what a changeable value, a function or expandMissionText() are.
et cetera.

A string is anything that contains text in code.
For example

Code: Select all

var myvariable = “some text I wrote”;

But also this

Code: Select all

this.functionCall(“text being passed into a function”);

A function is a segment of code that starts like this

Code: Select all

this.specialPurposeRoutine = function() {

A method is part of an object, and does something to, or with, that object.
For example

Code: Select all

player.ship.commsMessage

Here, there are two objects: the player object, and the ship object attached to the player object. commsMessage is a method attached to the players ship.

expandMissionText is a special function provided by the game engine that is used to pull information from the mission text.plist file.

Changeable values are any variables that have their contents changed through actions in the code. As distinct from a constant, which are variables that never change. JavaScript (or at least, our flavour of it) doesn’t officially support constants, but there are plenty of examples of variables being used as constants: look at any JS file, and at the top there will be this.name = “something”;. This value doesn’t change, and so can be considered a constant.

I get it, though, that it’s easy for me, who understands programming, to dump all that out. Making OXPs easier to localise is not something anyone can do, except perhaps for small OXPs. Quite often, when complex tasks are being performed, the original code needs to be abandoned in favour of something better suited to localisation.

[Cholmondely]

oolite.oxp.Cholmondely.Hints

Sir Simba,

I didn't write the code in "my" oxp, and I don't understand any of it! The oxp only came into existence because a bunch of people were good enough to help me - all I really did was scour these bulletin boards collecting advice and adding some advice of my own.

If you want to rewrite it all in some way that makes it easier for you, please do so. The important thing is giving advice to Oolite players (whether in the King's English or in Russian). The intricacies of the code are irrelevant as long as it works.

Here are some new hints to add to the current collection:

He was an idiot! An idiot, I tell you! He arrived at the witchpoint and was mobbed by pirates. But then, instead of fleeing, instead of handing over some canisters of cargo, the idiot fought! One against four, with just a pathetic pulse laser. He lasted thirty seconds. They shouldn’t let those idiots leave kindergarten!

So she arrived at Riedquat, and met the usual piratical welcome. She turned to escape and one of them - a mamba - was blocking her. She rammed it - mowed it down. Wouldn’t have worked on a bigger ship - or if she had been flying an adder. But she totally squashed that mamba… and then made a fortune in the markets at Riedquat.

ECMs do work against hard heads, you know! It’s just not very likely. I was out at Ensoreus a year ago and saw a Viper fire one at a pirate. The pirate turned and ran, but the hardhead was gaining… he hit his ECM so many times he turned himself into a fuzz-ball - but! On the fourth try he got it!
I was speaking with one of the mechanics - apparently the ECMs work by ion-saturation theory which has something to do with expanding nuclear flux-chains. Whatever. The point is that each time you hit the button, they emit three pulses of “counter-measures” - each has a chance of clobbering the missile.

No! Really? He didn’t bother to put his weapons on safe before docking?

No wonder the cops attacked him - he must have fired his lasers at something while docking! All he needed to do was to press the _ underscore key on his astrogation board. What an utter chump!

As with all the other hints, the important thing is the message. The English has been tweaked to make it more interesting/dramatic and to make it seem that a conversation at another table is being overheard. It is very idiomatic. Don't translate it word for word. Take the basic message and come up with something equally amusing in Russian and use that instead!

Basic messages
1 = Facing lots of pirates, dump cargo and flee - do not fight them with a pulse laser
2 = Smaller ships can be rammed
3 = Electronic Counter Measures (ECM) occasionally (once in a blue moon) works against Hard Heads/ECM Hardened Missiles
4 = Use "_" to toggle your weapons off before docking to avoid accidents




I'm hoping that between BeeTLe BeTHLeHeM, Phkb and Massively Locked, that a finished version of Life in the Frontier will appear before we all die of old age. And that Hints is put into it (something to do while wandering around the station and visiting the bar!). But I doubt that we'll be that lucky anytime soon... BB is busy at work, Phkb is doing more important things and ML is tending a very sick elderly mother...

[phkb]

If you want to rewrite it all in some way that makes it easier for you, please do so.

Here you go: Oolite.oxp.cholmondely.Hints.0.0.94.oxz
Give that a try, and if it still works OK, I'll update the manager.
I included the extra items you mentioned.

[phkb]

Therefore, I ask all addon developers to check their OXPs and make appropriate changes.

Perhaps what would be useful is a list of high-priority items that require immediate attention.

And a personal favour, maybe we could open a dialog with any OXP developers about making certain code changes, so that we don't end up having to debug two different versions of our own OXPs, one of which we've never seen before. 2 cases spring to mind: the issues Krager has experienced with Library; and the issues Krager has experienced with Loadout By Category.

[phkb]

A question: Do things like "Lave" and "Tionisla" also need translation?

[Wildeblood]

A question: Do things like "Lave" and "Tionisla" also need translation?

In the specific case of Russian, since it uses a different alphabet, every string, everywhere would need to be accounted for in some way. For other Latin-alphabet languages not so much.

[phkb]

In the specific case of Russian, since it uses a different alphabet, every string, everywhere would need to be accounted for in some way. For other Latin-alphabet languages not so much.

Good point. I'll include them in future.

[Cholmondely]

Here you go: Oolite.oxp.cholmondely.Hints.0.0.94.oxz
Give that a try, and if it still works OK, I'll update the manager.

Seems fine, thank you!

[Simba]

Perhaps what would be useful is a list of high-priority items that require immediate attention.

If we talk about things critical for localization, the main thing is to make strings in methods localizable. Miscellaneous technical information, such as logs or error messages, should not be touched. Strings in properties - not very convenient, but not very critical (but if the author of OXP in the next update decides to change the structure of the object in such a property, something may break).
If we are talking about specific OXPs, then priority should be given to those that are being actively developed. As I already described in the topic, the main problem of localization is support for updates. And if an extension hasn't been updated for a long time, the probability of new updates is low, so redefining methods and properties won't be critical.
I also understand that there can always be such “monsters” as the Galactic Almanac, which will take a lot of time just to translate the whole text, not to mention the preliminary refactoring for localizability. Nevertheless, in most of the cases I've seen, there are usually only a few problematic places - it comes down to putting the string in *.plist and replacing it with a call to expandMissionText().

And a personal favour, maybe we could open a dialog with any OXP developers about making certain code changes

I originally wanted to do that (that's why I started to make the OXP list), but it seems that such a dialog will still have to be conducted with the majority, so I decided to start a general topic, which can be referred to later.

so that we don't end up having to debug two different versions of our own OXPs, one of which we've never seen before. 2 cases spring to mind: the issues Krager has experienced with Library; and the issues Krager has experienced with Loadout By Category.

That's exactly what I'm trying to avoid, too. Krager is not a programmer and does the translation by directly changing the strings in the original OXPs. I am trying to translate not by modifying the original OXPs, but by creating separate OXP-localizers.

[Wildeblood]

In view of the above, there are some wishes for addon authors:
1) Avoid declaring strings inside methods;
2) If such strings are not some changeable values, then they should be stored in missiontext.plist or descriptions.plist, and in the code to get them by functions like expandMissionText();

Before creating the topic, I wanted to make a list of addons that have problems with localization, but after looking through a hundred, I found about 50 problematic ones. I decided not to continue - apparently, about half of all addons are problematic. Here are the ones that I managed to highlight:

oolite.oxp.CaptMurphy.PoliceIFFScanner

I have just now reviewed Police IFF Scanner, and the only string I could find in its script.js was this line:

this.equipmentDamaged = function (equipment) {
if (equipment === "EQ_POLICE_SCANNER_UPGRADE") {
player.consoleMessage("Police IFF Scanner Upgrade is Damaged!");
...

I had thought that the console messages that appear when equipment gets damaged came natively from within Oolite. So, does this line need an expandDescription(), or just for the line to be deleted?

[Simba]

I had thought that the console messages that appear when equipment gets damaged came natively from within Oolite. So, does this line need an expandDescription(), or just for the line to be deleted?

This message seems to correspond to “@-damaged” from the native descriptions.plist. If so, this explicit call is really unnecessary here.