Difference between revisions of "Translation ScratchPad"

From FreeOrionWiki
Jump to: navigation, search
 
(start of suggestion for solution)
Line 117: Line 117:
 
* Pick between multiple strings in a stringtable entry after it has been passed into another stringtable entry as a parameter, based on the flags associated with each string in the passed stringtable and the grammatical-context flags in the string into which the parameter was passed (whether statically attached or dynamically generated in response to another parameter)
 
* Pick between multiple strings in a stringtable entry after it has been passed into another stringtable entry as a parameter, based on the flags associated with each string in the passed stringtable and the grammatical-context flags in the string into which the parameter was passed (whether statically attached or dynamically generated in response to another parameter)
  
==Addendum==
+
===Addendum===
  
 
It is worth repeating that a major goal is to make this system language-independent.  The examples here are tempting to hard-code using English-relevant gender and plurality tests of some kind.  This is incompatible with various other languages however, which may have differing needs for gender and plurality modification, and which may have additional grammatical requirements unrelated to gender and plurality.  There is hopefully nothing about the undefined "flags" proposed here that would prevent other grammatical information from being conveyed and used in these languages as needed.
 
It is worth repeating that a major goal is to make this system language-independent.  The examples here are tempting to hard-code using English-relevant gender and plurality tests of some kind.  This is incompatible with various other languages however, which may have differing needs for gender and plurality modification, and which may have additional grammatical requirements unrelated to gender and plurality.  There is hopefully nothing about the undefined "flags" proposed here that would prevent other grammatical information from being conveyed and used in these languages as needed.
 +
 +
==Possible Solution: Flagged Text==
 +
 +
===Format===
 +
 +
====Current Non-Mutable Stringtable====
 +
 +
Stringtable entries consist of an all-CAPS token name, followed by the human readable text.  For example:
 +
 +
DIPLO_TEXT
 +
Greetings, $LEADERNAME1.  $LEADERNAME2 salutes you!
 +
 +
The above is a simple diplomatic message with two parameter values.  The game code knows the token DIPLO_TEXT, and reads the appropriate string following this token in the various language files.  Different language files are used for each language for localization.
 +
 +
The $LEADERNAME1 and $LEADERNAME2 in the human readable text are parameters.  They are replaced with the text of other stringtable entries, or equivalent information, by the game code.
 +
 +
A string substituted for $LEADERNAME1 might be
 +
 +
HUMAN_RULER
 +
Gary Coleman
 +
 +
This might be specified in a stringtable file, such as for predefined races, or might be player-entered.
 +
 +
Parameters are of fixed number and type for each string, and are sufficient only to convey the information necessary to complete the string in a language-independent sense.  In this case, the string is a greeting between one leader and another.  The string is generic, permitting the specific leaders to be altered, but no other aspects of the string can be changed by passing extra parameters.
 +
 +
====Flags====
 +
 +
It is proposed to add a facility to add "flags" to stringtable entries in order to convey additional information that is not directly displayed to the player, but which is used to alter what is displayed, or to selected between options of what to display to the player.
 +
 +
The specific format of flags is undertermined, but it is important that a string without any flags looks exactly like the above examples of simple unmutable stringtable text.
 +
 +
For illustrative purposes, it is proposed to indicate flags in stringtable entries like so:
 +
 +
EXAMPLE_TOKEN
 +
some text, for example<flag><other flag>
 +
 +
The above text, with attached flags, would be inserted into another string, such as:
 +
 +
TOKEN_WITH_PARAMETER
 +
This is the text with $PARAMETER in it.
 +
 +
Without any additional markup, if TOKEN_WITH_PARAMETER was displayed to the player with EXAMPLE_TOKEN passed as the value of $PARAMETER, the player would see
 +
 +
This is the text with some text for example in it.
 +
 +
The flags, contained within the <> brackets, are not displayed.
 +
 +
In order to use flags, some additional markup is needed to test for their presence.
 +
 +
FLAGTEST_TOKEN
 +
Here's a mutable string: It <if $PARAM has flag>has the flag!</if><if $PARAM has not flag>does not have the flag.</if>
 +
 +
If EXAMPLE_TOKEN was passed to FLAGTEST_TOKEN as a parameter, and EXAMPLE_TOKEN was displayed to the player, the player would see:
 +
 +
Here's a mutable string: It has the flag!
 +
 +
The passed parameter is tested for the presence of a specific flag (here named "flag").
 +
 +
Note that the parameter does not explicitly appear in the string displayed to the player, despite actually containing some text.  The parameter text is only actually displayed (without flags) if it appears outside of <> blocks.
 +
 +
Note also that the parameter appears twice.  This is the same parameter tested twice in the string into which it is passed.  It is still only a single parameter however, as it has the same parameter name.  The single parameter could appear as many times as necessary, in any combination of diplayed (outside <> blocks) and tested for flags (inside <> blocks) as is necessary.

Revision as of 11:40, 22 January 2005

Preamble

This is a verbose discussion of issues relating to stringtables, grammar and translations.

Principles

Language independence of game code (Primary Importance)

  • No sentence sythesis from words or phrases
    • Fully formed sentences that self-modify according to parameters or context OK
      • Parameters / context options defined in stringtable
  • Strings that change according to context described fully in stringtable
    • No grammar concepts built into code (as different languages have different rules for this, and hard-coding will limit translators
      • Gender
      • Plurality
      • Other more obscure grammar rules or information
    • Parameters to strings like %1% only for conceptually necessary information. No added strings to pass conjugations or pronouns.
      • This information should be contained (as markup?) in relevant passed parameter, if at all

Simplicity (Secondary Importance)

  • Simple cases default to plain text
    • No markup for non-mutable text
  • Avoid "programming" concepts like functions and passing parameters
    • Difficult rule to follow.
      • Self-modification due to context acts somewhat like a parameter, but hopefully can be made to not "seem" like parameters are being passed, so translators don't need to know the difference

Justification: Problems that cannot be resolved with simple unmutable stringtables

Note on symbols

In the following examples, text enclosed in "" are stringtable entries. $WORDS starting with $ and in all CAPS are parameters in the stringtable entry. The game code would supply the text of another stringtable entry or a numerical value for these parameters.

Parameter to string changes text of string

(Examples)

Flagged parameter changes plain text

"I like $RULERNAME. He/She is nice"

$RULERNAME text might be "John" or "Jane"

Based on gender of parameter $RULERNAME, must pick between "He" and "She" in text of this string. This requires information about the gender of $RULERNAME to be passed with the string parameter $RULERNAME, and tested against options in string to determine correct text to use.

Numeric parameter changes plain text

"I ate $AMOUNT grape/grapes. It/they was/were good."

$AMOUNT is a positive integer

Based on numerical value of parameter $AMOUNT, must pick between various plurality-varying forms of several words in this string. This requires the numerical value of $AMOUNT to be compared to values encoded in the string, and the results of the comparison used to determine the correct text to use.

In general

Need to be able to:

  • Attach arbitrary flags to stringtable entries to allow sentence strings to which they are passed to self-modify to accomodate the passed string.
  • Test numerical values of parameters to determine which form of words to use in string.
Note

The object, "grape/grapes", is fully contained within its string, so there is no need to evaluate a parameter to determine the gender of the object in order to select the correct pronoun, verb conjugation and adjective in the second sentence in English. In practice, this sort of sentence would probably be more general-purpose, using a parameter for the object, meaning the gender (or other grammatical information) about the object would need to be asertained to correctly form the rest of the sentence. This will probably require the ability to attach flags to strings that act as parameters, which descibe the grammatical form of the parameter to the string in which it is used.

Note

Could possibly pass a flag to indicate plurality as well. This would require defining a standard plurality test elsewhere in the stringtable (not in code). This test cannot be done in code because some languages have other degrees of plurality (eg. single, dual, and plural) than does English, meaning any hard-coded test wouldn't be language-independent.

Note

Whether testing plurality by flags or in-string tests, it will be necessary to be able to test for more than one flag simultaneously, or flags in addition to numerical values of parameters. The singularity/plurality and gender flags cannot be combined into a single flag like SINGULARPLURAL, as the sources of the gender and plurality information may be separate parameters for a given noun.

Context of string changes text of parameter to string

Context in string is fixed (not variable dependent on anything else)

Context fully established with flags in string taking in parameter

"Give me two $THING"

$THING text might be "banana" or "bananas"

Based on the numerical value in context of string, must pick between various plurality-varying forms of word in the parameter. This requires the string passed to internally contain several forms which can be chosen between in response to the context of the string into which it is passed.

Context determined by other parameter value

Context established by other numeric parameter

"Give me $AMOUNT $UNIT of $RESOURCE"

$AMOUNT is a positive integer
$UNIT text might be "barrels" or "barrel"
$RESOURCE text is "oil"

Based on numerical value of parameter $AMOUNT, must pick between plurality-varying forms of word in parameter $UNIT. This requires the numerical value of $AMOUNT to be compared to values encoded in either this string, or in the stringtable entry for $UNIT, and the results of the comparison used to to determine the context. This also requires the passed string $UNIT to internally contain several forms which can be chosen between in response to the context of the string into which it is passed (determined by another parameter in this case).

Note

Ideally, the stringtable entry for $UNIT would not need to be written differently in order to distinguish between being passed into a string which has a fixed context and one which has a context that depends on another parameter. Thus it is probably desirable to have the string into which both parameters are passed do all the comparisons, and then dynamically establish its context, and then do the selection between the various forms of the mutable string it was passed. (As opposed to conceptually having the passed mutable string ($UNIT in this case) contain the logic that selects which form to use)

Context established by other flagged parameter

"$LEADER is very $COMPLEMENT"

$LEADER text might be "John" or "Jane"
$COMPLEMENT text might be "Dashing" or "Beautiful"

Based on gender of parameter $LEADER, gender-varying forms of word in parameter $COMPLMENT. This requires information about the gender of $LEADER to be passed with the string parameter $RULERNAME, and tested against options in string to determine context. This also requires the passed string $COMPLEMENT to internally contain several forms which can be chosen between in response to the context of the string into which it is passed (determined by another parameter in this case).

In general

Need to be able to:

  • Make a single stringtable entry consist of multiple strings, each associated with flags or combinations of flags
  • Attach flags to stringtable entries into which other stringtable entries are passed, in order to indicate grammatical context about the string
  • Test numerical values of parameters to determine context of a string
  • Pick between multiple strings in a stringtable entry after it has been passed into another stringtable entry as a parameter, based on the flags associated with each string in the passed stringtable and the grammatical-context flags in the string into which the parameter was passed (whether statically attached or dynamically generated in response to another parameter)

Addendum

It is worth repeating that a major goal is to make this system language-independent. The examples here are tempting to hard-code using English-relevant gender and plurality tests of some kind. This is incompatible with various other languages however, which may have differing needs for gender and plurality modification, and which may have additional grammatical requirements unrelated to gender and plurality. There is hopefully nothing about the undefined "flags" proposed here that would prevent other grammatical information from being conveyed and used in these languages as needed.

Possible Solution: Flagged Text

Format

Current Non-Mutable Stringtable

Stringtable entries consist of an all-CAPS token name, followed by the human readable text. For example:

DIPLO_TEXT
Greetings, $LEADERNAME1.  $LEADERNAME2 salutes you!

The above is a simple diplomatic message with two parameter values. The game code knows the token DIPLO_TEXT, and reads the appropriate string following this token in the various language files. Different language files are used for each language for localization.

The $LEADERNAME1 and $LEADERNAME2 in the human readable text are parameters. They are replaced with the text of other stringtable entries, or equivalent information, by the game code.

A string substituted for $LEADERNAME1 might be

HUMAN_RULER
Gary Coleman

This might be specified in a stringtable file, such as for predefined races, or might be player-entered.

Parameters are of fixed number and type for each string, and are sufficient only to convey the information necessary to complete the string in a language-independent sense. In this case, the string is a greeting between one leader and another. The string is generic, permitting the specific leaders to be altered, but no other aspects of the string can be changed by passing extra parameters.

Flags

It is proposed to add a facility to add "flags" to stringtable entries in order to convey additional information that is not directly displayed to the player, but which is used to alter what is displayed, or to selected between options of what to display to the player.

The specific format of flags is undertermined, but it is important that a string without any flags looks exactly like the above examples of simple unmutable stringtable text.

For illustrative purposes, it is proposed to indicate flags in stringtable entries like so:

EXAMPLE_TOKEN
some text, for example<flag><other flag>

The above text, with attached flags, would be inserted into another string, such as:

TOKEN_WITH_PARAMETER
This is the text with $PARAMETER in it.

Without any additional markup, if TOKEN_WITH_PARAMETER was displayed to the player with EXAMPLE_TOKEN passed as the value of $PARAMETER, the player would see

This is the text with some text for example in it.

The flags, contained within the <> brackets, are not displayed.

In order to use flags, some additional markup is needed to test for their presence.

FLAGTEST_TOKEN
Here's a mutable string: It <if $PARAM has flag>has the flag!</if><if $PARAM has not flag>does not have the flag.</if>

If EXAMPLE_TOKEN was passed to FLAGTEST_TOKEN as a parameter, and EXAMPLE_TOKEN was displayed to the player, the player would see:

Here's a mutable string: It has the flag!

The passed parameter is tested for the presence of a specific flag (here named "flag").

Note that the parameter does not explicitly appear in the string displayed to the player, despite actually containing some text. The parameter text is only actually displayed (without flags) if it appears outside of <> blocks.

Note also that the parameter appears twice. This is the same parameter tested twice in the string into which it is passed. It is still only a single parameter however, as it has the same parameter name. The single parameter could appear as many times as necessary, in any combination of diplayed (outside <> blocks) and tested for flags (inside <> blocks) as is necessary.