Translations - Revision history

Thoun at 10:07, 16 September 2026

2026-09-16T10:07:47Z

← Older revision		Revision as of 12:07, 16 September 2026
Line 335:		Line 335:
	On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.		On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
	It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.		It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.

			== Testing translations on Studio ==

			On a studio table, add "&dummyTranslations" to the URL to test the translations. All the front-side translations (using <code>_('...')</code> on the front side) should display surrounded by «» to mark translatable text.

	== Using translations from a base project ==		== Using translations from a base project ==

Victoria La: /* Gender specific pronouns */

2026-07-04T15:31:57Z

Gender specific pronouns

← Older revision		Revision as of 17:31, 4 July 2026
Line 111:		Line 111:
	Possessive pronouns		Possessive pronouns
	* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).		* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
	* ~~Also avoid "their".~~ The pronoun replacement system ~~cannot work if your use~~ "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to his hand" and not "playerX returns card to their hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")		* The pronoun replacement system does not change word "their" as a singular genderless pronoun. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")
	* If possible re-phrase to not use possessive either: "returns card to the hand" or "returns card to player's hard" is better.		* If possible re-phrase to not use possessive either: "returns card to the hand" or "returns card to player's hard" is better.

Victoria La: /* Gender specific pronouns */

2026-07-02T22:05:38Z

Gender specific pronouns

← Older revision		Revision as of 00:05, 3 July 2026
Line 103:		Line 103:
	== Gender specific pronouns ==		== Gender specific pronouns ==

	* Avoid using gender-specific wording as much as possible.		'''Avoid using gender-specific wording as much as possible'''

			Subject pronouns
			* Do not use subject pronouns (he, she), use ${player_name} or word "player" if needed. Word "they" is fine in English (plural) but may be not in other languages (like French), so avoid using it also (use "players" or similar nouns).
			* Do not use weird stuff like he/she or s/he, see about on how to replace them

			Possessive pronouns
	* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).		* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
	* Also avoid "their". The pronoun replacement system cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to his hand" or "playerX returns card to his/her hand" and not "playerX returns card to their hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")		* Also avoid "their". The pronoun replacement system cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to his hand" and not "playerX returns card to their hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")
			* If possible re-phrase to not use possessive either: "returns card to the hand" or "returns card to player's hard" is better.

	== WARNING: Make sure your strings will be translated! ==		== WARNING: Make sure your strings will be translated! ==

Victoria La: /* How to not make translators crazy ;) */

2026-07-02T21:26:58Z

How to not make translators crazy ;)

← Older revision		Revision as of 23:26, 2 July 2026
Line 99:		Line 99:
	* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".		* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
	* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".		* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
			* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But never do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

			== Gender specific pronouns ==

	* Avoid using gender-specific wording as much as possible.		* Avoid using gender-specific wording as much as possible.
	* ~~Also avoid "their".~~ There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, ~~and~~ cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to his hand" or "playerX returns card to his/her hand" and not "playerX returns card to their hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")		* There is [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place however it is limited to replace possessive pronouns (his, her, their), not subject pronouns (he, she, they).
	* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But never do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.		* Also avoid "their". The pronoun replacement system cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to his hand" or "playerX returns card to his/her hand" and not "playerX returns card to their hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting. In some case its actually needed, for example if you say "King sends his troops" in the log and King is not a player name, but character in the game - it will be changed to "her" if a player is female, which is not correct, in this case their would be appropriate (or just "the troops")

	== WARNING: Make sure your strings will be translated! ==		== WARNING: Make sure your strings will be translated! ==

Thoun at 15:25, 26 February 2026

2026-02-26T15:25:02Z

@@ Line 245: / Line 245: @@
                  'i18n' => array( 'card_name' ),     // <===== We specify here that "card_name" argument must be translated
                  'player_id' => $player_id,
-                 'player_name' => self::getActivePlayerName(),
+                 'player_name' => $this->getPlayerNameById($player_id),
                  'points' => $points,
                  'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
@@ Line 264: / Line 264: @@
 '''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).
 ==== Throwing an exception because the player did a forbidden move ====

Thoun at 10:25, 13 February 2026

2026-02-13T10:25:49Z

← Older revision		Revision as of 12:25, 13 February 2026
Line 218:		Line 218:
	<pre>		<pre>
	// A game log string with no argument:		// A game log string with no argument:
	$this->notify->all( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );		$this->bga->notify->all( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
	</pre>		</pre>

Line 225:		Line 225:
	<pre>		<pre>
	notif="foo";		notif="foo";
	$this->notify->all( 'log', clienttranslate(notif),[]); // BAD		$this->bga->notify->all( 'log', clienttranslate(notif),[]); // BAD

	notif=clienttranslate("foo");		notif=clienttranslate("foo");
	$this->notify->all( 'log', notif,[]); // GOOD		$this->bga->notify->all( 'log', notif,[]); // GOOD

	$this->notify->all( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php		$this->bga->notify->all( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
	$this->notify->all( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes		$this->bga->notify->all( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

	$this->notify->all( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation		$this->bga->notify->all( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

	</pre>		</pre>
Line 242:		Line 242:
	// In the following example, we translate the game log itself, but also the "card_name" argument:		// In the following example, we translate the game log itself, but also the "card_name" argument:

	$this->notify->all( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(		$this->bga->notify->all( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
	'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated		'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
	'player_id' => $player_id,		'player_id' => $player_id,

Thoun: /* Using translations from a base project */

2025-11-17T15:39:26Z

Using translations from a base project

← Older revision		Revision as of 17:39, 17 November 2025
Line 310:		Line 310:
	== Using translations from a base project ==		== Using translations from a base project ==

	In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact ~~use~~.		In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact us using https://studio.boardgamearena.com/support.

	== Other Useful Links ==		== Other Useful Links ==

Thoun at 15:38, 17 November 2025

2025-11-17T15:38:57Z

← Older revision		Revision as of 17:38, 17 November 2025
Line 307:		Line 307:
	On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.		On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
	It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.		It also will extract all you translation keys as translator will see them so you can double check - and run spell checker on them.

			== Using translations from a base project ==

			In some cases, when 2 projects share a big part of the same code (example: Ticket to Ride and Ticket to Ride Europe), you might not want the translators to re-translate every sentence in common for every language. We have an experimental feature to avoid translations of sentences that are common, if you are concerned for a new project please contact use.

	== Other Useful Links ==		== Other Useful Links ==

Thoun at 16:02, 22 October 2025

2025-10-22T16:02:38Z

← Older revision		Revision as of 18:02, 22 October 2025
Line 269:		Line 269:
	<pre>		<pre>
	// This will display a translatable red message to the player that just did some wrong action:		// This will display a translatable red message to the player that just did some wrong action:
	throw new ~~\BgaUserException~~(clienttranslate('You must choose 3 cards'));		throw new UserException(clienttranslate('You must choose 3 cards'));
	</pre>		</pre>

	Note that the use of ~~\BgaUserException~~ signals that this exception is "expected". In theory, all exception that are expected should be translated.		Note that the use of UserException signals that this exception is "expected". In theory, all exception that are expected should be translated.

	<pre>		<pre>
	// this is the same but with variable		// this is the same but with variable
	throw new ~~\BgaUserException~~(clienttranslate('You must choose ${n} cards'), ~~args:~~ ['n' => $card_num]);		throw new UserException(new NotificationMessage(clienttranslate('You must choose ${n} cards'), ['n' => $card_num]));
	</pre>		</pre>

Thoun: /* Function clienttranslate */

2025-09-19T14:38:27Z

Function clienttranslate

← Older revision		Revision as of 16:38, 19 September 2025
Line 199:		Line 199:

	In general, you use clienttranslate:		In general, you use clienttranslate:
	* In your '''~~states.inc.php~~''', for the fields "description" and "descriptionmyturn".		* In your '''Game state classes''', for the fields "description" and "descriptionmyturn".

	<pre>		<pre>
	"description~~" =>~~ clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),		description: clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
	</pre>		</pre>