Skip to content

Translation and Localization

Jump to bottom Edit New page
Xansta edited this page Nov 1, 2024 · 22 revisions

This page documents the ongoing effort of facilitating the translation of EmptyEpsilon for different languages.

There are five major aspects that need to be worked on:

  1. Updating the C++ code to allow for translations
  2. Updating shared Lua code to allow for translations
  3. Updating scenarios to allow for translations
  4. Adding translations of game text
  5. Adding translations of shared Lua script and scenario text
  6. Examples of different files that need translation

Updating the C++ code to allow for translations

EmptyEpsilon was not designed for translation or localization, and many parts still need to be updated.

Most translation patches look like this: https://github.com/daid/EmptyEpsilon/pull/1732/commits/3bfbc7deb2f720a677d85f232a9605ba8e95b563

The tr() function is added around static strings in the code so they can be translated. The function can be used with either one or two parameters.

Using tr() with two parameters provides context for the string in the first parameter. This context can help clarify the string's translation. For example, translating the string "Both" can be difficult without context, but the context "jump/warp" indicates that this is about jump/warp selection, which helps translators use the correct word for their language.

Pull requests to add translation contexts are welcome, but try to make small changes in order to make reviews easier and avoid introducing bugs. Some updates are more complex than simply combining translation contexts or strings and require more complex changes to properly format or implement.

Updating shared Lua code to allow for translations

To update common Lua-language content shared across scenarios and game features, such as ship templates, science database, and main comms scripts, use the _() function.

Just like the tr() function in C++, the _() function in Lua can accept either one or two parameters, with the first parameter in two-parameter usage providing the context. (Example)

Some strings that replace a part of the content with a dynamic value might require the string.format() function instead of simple string concatenation ("" .. ""). Take care when adding or translating strings that use the string.format() function, because the replacement value might unexpectedly change the translation context.

Updating scenarios to allow for translations

Like shared Lua code, Lua-language scenarios use _() function calls to provide translation contexts. However, scenarios often contain more string.format() functions than shared Lua scripts. (Example)

To reduce the burden of maintenance, please work on only a single scenario at a time and per pull request.

Adding translations of game text

Translations of the EmptyEpsilon interface and non-scenario game text are stored in gettext catalog (.po) files in the resources/locale directory, currently copies of https://github.com/daid/EmptyEpsilon/blob/master/resources/locale/main.en.po with different filenames for each translated language. You can use Poedit, a free and open-source translation editor, to add and edit translations in such files.

After someone changes or adds a feature in the EmptyEpsilon user interface involving a string, the game's main English translation file must be updated first. Copies can then be made for other language translations to update.

To update the main English translation file, run the Makefile target "update_locale" (make update_locale). However, please do not update the main English locale file in pull requests. This will be done by a project maintainer directly on the master branch. (Example)

Adding translations of shared Lua script and scenario text

Each scenario file, including the tutorials, and shared Lua script file should also have a corresponding .po translation file in the scripts/locale directory. For example, the French translation file for scripts/scenario_03_waves.lua is located at scripts/locale/scenario_03_waves.fr.po. As science database it fed from multiple sources (ship templates, faction info), its translation is stored in multiple files in the scripts/locale directory and sub-directories. While EmptyEpsilon loads translations automatically if present, no script generates the initial translation file.

Best practices

Non-Latin characters in translations

EmptyEpsilon has basic Unicode support for text labels, but not text input boxes, since version 2021.03.16. Non-ASCII characters should work. Test changes that introduce non-ASCII characters before filing a pull request.

Earlier versions of EmptyEpsilon did not support Unicode or ISO-encoding. If you are translating scenarios for older versions of EmptyEpsilon, if possible use no letters outside of the Latin alphabet and use substitution rules if they exist for the target language.

Standardization of translation contexts

The contexts of translation tags in scenarios included in EmptyEpsilon are standardized in order to facilitate translation, but also to demonstrate to authors of future scenarios how to add the tags themselves. A lot of retroactive work has been done on translations of scenarios, but ideally scenario authors can add translation tags when writing a scenario.

In a translation context, there are two distinct components separated by a dash "-":

  1. The place where the text to be translated is found in the game, such as the shipLog, science, comms, etc. This sometimes helps to indicate that the available space for text is limited, such as for button, Tab, and msgMainscreen text. For example, French translations often result in longer text than the original English, so this context helps French translators use more concise or abbreviated text.
  2. Contextualizing the text in the scenario's plot, which allows translators to better understand the text's meaning and avoid off-topic or mistaken translations of expressions with no equivalent in the translated language. This particularly helps translators who do not know the scenario well.

In translation software like Poedit, translators can sort by context. Depending on the scenario, it is sometimes more judicious to reorder these components for sorting. (Example)

Reusing common text in scenarios

To save time when translating scenarios authored by @Xansta, translators can also copy and paste from the common text "database" that Xansta sometimes uses in these scenarios. For example, in scenario_55_defenderHunter.lua, 400 translatable strings are also used in other scenarios.

List of contexts

Notation Legend

I = Contexts and their content Identical from one scenario to another - often repeated in some Xansta scenarios.
D = multi-scenario contexts but with Different content.
U = Contexts Unique to their scenario (surely no duplication elsewhere).

OK = check in progress
>> = final context
() = secondary

If possible, avoid using the same exact names as the functions to make it easier to find and to avoid errors when making changes.

M = Main.po
1 = Deliver Ambassador Gremus
2 = What the Dickens
3 = Pvp
4 = Escape
5 = Defender Hunter
6 = Gaps
7 = Allies and Enemies
8 = Basic
9 = Waves
A = Training
B = Beacon of Light
C = Edge of Space
D = Atlantis
E = gftp

Context Groups

Communications (comms)

>>OK		   needRep-comms	I	 1234567    C
>>OK    	    gossip-comms	I	    4567
>>OK		      ship-comms	I	M   4567
>>OK		shipAssist-comms	I	M   4567
>>OK		 shipEnemy-comms	I(D)	M  34567
>>OK		   station-comms	I(D)	M1234567    CD
>>OK   	      stationStory-comms	I(D)	    4567
>>OK  	     stationAssist-comms	I	 12 4567    C
>>OK    stationGeneralInfo-comms	I	    4567
>>OK	   	      ammo-comms	I(D)	 1234567    C
>>OK		     trade-comms	I(D)	    4567 include ship & station
>>OK	   explainGoods...-comms	I	    45 7
>>OK 		   upgrade-comms	I(D)	     5
>>OK	     upgradeOrders-comms	I(D)	     56
>>OK     	    orders-comms	D(I)	 12  567
>>OK        artifactOrders-comms	U	 1
>>OK        doomsdayOrders-comms	U	       7
>>OK              doomsday-comms	U	       7
>>OK          doctorOrders-comms	U	       7
>>OK                doctor-comms	U	       7
>>OK          BespinOrders-comms	U	       7
>>OK	     characterInfo-comms	U	       7
>>OK              artifact-comms	D	 1          D
>>OK    	      path-comms	D	 1     7
>>OK     	      goal-comms	U	     5
>>OK	    reinforcements-comms	U	   3
>>OK	   situationReport-comms	U	   3
>>OK       areaDescription-comms	U	  2
>>OK           crewFriends-comms	U	    4
>>OK		 minefield-comms	U	      6
>>OK 	   helpfullWarning-comms	I(D)	     56
>>OK dockingServicesStatus-comms	U	     5
>>OK		     Maria-comms	U	     5
>>OK	       MariaOrders-comms	U	     5
>>OK	      intelligence-comms	U	     5
>>OK	intelligenceOrders-comms	U	     5
>>OK		   upgrade-comms	U	     5
>>OK	      defTelemetry-comms	U	     5
>>OK		      Paul-comms	U	     5
>>OK		PaulOrders-comms	U	     5
>>OK		 HMSBounty-comms	U	     5
>>OK	    centralcommand-comms	U	            C
>>OK  centralcommandOrders-comms	U	            C
>>OK	       JumpCarrier-comms	U	             D
>>OK		     swarm-comms	U	              E
>>OK		       NSA-comms	U	 	      E 
>>OK	      Lightbringer-comms	U		      E
>>OK		HackedShip-comms	U		      E

Ship's Log (shipLog)

    		       ...-shipLog
>>OK                   	   shipLog	D	  2      9   
>>OK          	      goal-shipLog	D	  2 4 6  9
>>OK          	BespinGoal-shipLog	U	       7
>>OK          	doctorGoal-shipLog	U	       7
>>OK          doomsdayGoal-shipLog	U	       7
>>OK              doomsday-shipLog	U	       7
>>OK                doctor-shipLog	U	       7
>>OK                Bespin-shipLog	U	       7
>>OK             inventory-shipLog	U	       7
>>OK        	     audio-shipLog	D	 12
>>OK		 goalAudio-shipLog	U	     5
>>OK	       ordersAudio-shipLog	U	  2	
>>OK 	 	 minefield-shiplog	U	      6
>>OK       	   upgrade-shipLog	U	 1
>>OK	            return-shipLog	U	  2
>>OK	       returnAudio-shipLog	U	  2
>>OK	      riverWarning-shipLog	U	  2
>>OK          	crewRepair-shipLog	U	    4
>>OK           crewFriends-shipLog	U	    4
>>OK	   	  transfer-shipLog	U	    4
>>OK		     Boris-shipLog	U	    4
>>OK 	   helpfullWarning-shipLog	U	     5
>>OK		     Maria-shipLog	U	     5
>>OK	        MariaAudio-shipLog	U	     5
>>OK	  MariaOrdersAudio-shipLog	U	     5
>>OK	upgradeOrdersAudio-shipLog	U	     5
>>OK	  	 HMSBounty-shipLog	U            5
>>OKintelligenceOrdersAudio-shipLog	U	     5
>>OK		      Paul-shiplog	U	     5
>>OK	        PaulOrders-shiplog	U	     5

Incoming Call (incCall)

      		  	   ...incCall	D	           B DE
>>OK	     		audio-incCall	U	 1
>>OK	     		 goal-incCall	D	   3    8 AB DE
>>OK			Boris-incCall	U	    4
>>OK	  	   crewImport-incCall	U	    4
>>OK	 	  	 Paul-incCall	U	     5
>>OK	 	    	 time-incCall	U	        8
>>OK	   centralcommandGoal-incCall	U	            C
>>OK	       centralcommand-incCall	U 	            C E
>>OK	 centralcommandOrders-incCall	U 	            C
>>OK	     technicalofficer-incCall	U	            C
>>OK		      Galileo-incCall	U 	            C
>>OK	       KraylorEndline-incCall	U	            C
>>OK		 KraylorMline-incCall	U	            C
>>OK			human-incCall	U	            C
>>OK		    shipEnemy-incCall	U	             D
>>OK		  JumpCarrier-incCall 	U		     D
>>OK		      station-incCall	U		     D

Call Sign or Name (callsign)

		callsign-...
>>OK		callsign-station	U	            C
>>OK		callsign-ship		U	            C

Science Description (scienceDescription)

       scienceDescription-...		
>>OK   scienceDescription-station	I(D)	 12 4567      E
>>OK   scienceDescription-planet	D	    45 7
>>OK   scienceDescription-artifact	D	 12  5       D
>>OK   scienceDescription-debris	U	    4
>>OK   scienceDescription-buoy		U	    4

Zone Label Description (ZoneLabelDescription)

   	ZoneLabelDescription-...	
>>OK   	ZoneLabelDescription-junk	U	    4
>>OK   	ZoneLabelDescription-faction	U	       7

Message (msg)

  		     ...-msg<>-...
>>OK		         msgMainscreen	D	 12 45 7 9A CDE
>>OK		doomsday-msgMainscreen	U	       7
>>OK		  doctor-msgMainscreen	U	       7
>>OK		  bespin-msgMainscreen	U	       7
>>OK	      msgMainscreen&Spectbanner U	        8
>>OK	      msgMainscreen-bonusTarget	U	          A
>>OK			 msgSpectbanner U	        8     
>>OK		         msgEngineer	D	    4567
>>OK		         msgEngineer+	D	    4567
>>OK			 msgHelms	U	     5
>>OK			 msgOperations	U	     5
>>OK			 msgScience	U	     5
>>OK			 msgTactical	U	     5
>>OK			 msgRelay	U	     5
>>OK		     air-msgEngineer	U	    4
>>OK	 	     air-msgEngineer+	U	    4
>>OK		     air-msgOperations	U	    4
>>OK		     air-msgScience	U	    4
>>OK		     air-msgMainscreen	U	    4
>>OK		transfer-msgEngineer	U	    4
>>OK	 	transfer-msgEngineer+	U	    4
>>OKcrewRepairStatut-msgRelay&OperationsU	    4
>>OK		   audio-msgMainscreen	U	 1
>>OK		artifact-msgScience	U	 1

Tab or Information Banner from Custom Info (tab)

	    ...-tab<>...
>>OK       	tabEngineer		I	    45 
>>OK   airTimer-tabScience&Eng&Eng+&Ops	U	    4
>>OK    coolant-tabEngineer		U	       7
>>OK    doomsday-tabEngineer&Engineer+	U	       7
>>OK     doctor-tabScience&Operations	U	       7
>>OK	  audio-tabRelay&Operations	U	 1
>>OK	tabRelay&Ops-homeStationHealth	U	     5

Button Text (button)

         	  ...-button<>
>>OK	              buttonGM		D	  2 4567
>>OK	    inventory-buttonRelay	U	       7
>>OK	    inventory-buttonOperations	U	       7
>>OK	      coolant-buttonEngineer	U	       7
>>OK	      coolant-buttonEngineer+	U	       7
>>OK      	audio-buttonRelay	U	 1
>>OK	   crewImport-buttonWeapons  	U	    4
>>OK	   crewImport-buttonTactical  	U	    4
>>OK	     transfer-buttonEngineer	U	    45
>>OK	     transfer-buttonEngineer+	U	    45
>>OK crewRepairStatut-buttonRelay	U	    4
>>OK crewRepairStatut-buttonOperations	U	    4

Back (Back)

>>OK    		   Back		I	 1234567    C

Examples of different files that need translation

scripts/science_db.lua                 scripts/factionInfo.lua           scripts/shiptemplates/corvette.lua
scripts/shiptemplates/dreadnaught.lua  scripts/shiptemplates/exuari.lua  scripts/shiptemplates/frigates.lua
scripts/shiptemplates/ktlitan.lua      scripts/shiptemplates/OLD.lua     scripts/shiptemplates/transport.lua

This is not an exhaustive list, just an example of some of the files that need translation

Add a custom footer
Clone this wiki locally