poglang: Draft Proposal

[SOF3]

This issue serves as a draft proposal to the "poglang" translation framework. A conclusion of the discussion of poglang will be migrated to its own repo when it gets created.

What is this about?

poglang is a translation framework powered by Poggit. Why Poggit? Because it consists of several components that use Poggit's service.

The flow

1. The developer creates a base language file and enables poglang in .poggit.yml. The changes are received by Poggit through a GitHub commit.
2. Translating

• An unofficial translator visits Poggit's translation page and edits the translations online. ("Proposed")
• Other unofficial translators/reviewers visit Poggit's translation page and vote to approve it. ("Voted")
• Official translators/reviewers (the developer, or people appointed by the developer) approve the translations. ("Approved")

3. Each time Poggit-CI builds the project, the latest translation data are injected into resources/poglang. Three versions (Proposed, Voted, Approved) will be injected in respective subdirectories.
4. When the plugin is executed, it tries to update the language files from Poggit's API.

Crowdsourced Translation Online

Few plugin developers know many languages from multiple continents. Very few plugin developers (virtually none) would hire a translation team for their plugin. Automatic translation tools like Google Translate are unreliable and almost unreadable. The only translation solution that plugin developers are left with is crowdsourcing — let the international fans of the plugin do the translation work.

Translators can visit a page like /tr/{OwnerName}/{RepoName}/{ProjectName} to propose translations, where others will see it and vote to go through a vote-approve procedure similar to the flow in Poggit Release, except there isn't a "Checked" stage.

Why not Crowdin?

Crowdin is cool, but it isn't easy or affordable to setup for everyone. Just as always, Poggit aims to turn the difficult and annoying things in plugin development simple by integrating them in Poggit, and this time it aims for easy translations.

When will this be available?

We want poglang to be released as its best state without incompatible updates, so this will be a slow progress.

Things requesting for comment

Base language file

• Data declared
  • Description
  • Value in English
  • Arguments
  • Support conditionals
  • Constants
    • Used for systematic coloring
    • Maybe some common terms too
  • Versioning each translation (in case the desired value is changed)
  • Inheritance, e.g. Chinese Simplified inherits Chinese Traditional
• File Format
  • JSON
    • Might not look nice with attributes like description etc.
  • XML
    • Closing tags are annoying
  • Custom format
    • How?
• Argument replacing
  • How should be the format of the "default translation" to escape translations, do formatting, etc.?

Customizable format

• A possibility is to allow users to edit the language files, so the format downloaded from Poggit has to be editor-friendly.

Plugin API

• Is it possible to allow auto-completion in IDEs?
  • What about making a script that autogenerates a constant enum class from the base language file?
• Any better method than the old get("k.e.y") syntax?
  • Make it possible to internally pass the desired translation as key without resolving the actual value.

[Feluu]

Nice idea

[xBeastMode]

Ohhh that's cool. I wanna see this 😄

[TheDiamondYT1]

Why isn't YAML up there?

[SOF3]

@TheDiamondYT1 You mean the base language file? I assume JSON and YAML to be the same thing.

[jasonw4331]

can we add ini file format? MyPlot uses that and it could allow for PocketMine translations too

[SOF3]

@jasonwynn10 INI for the base language file or the translation files downloaded?

For base language file, no, because INI does not support attributes well.

[SOF3]

Proposed example of base language file: semi-HTML formatting.

lang: base

# "Terms" are some terms that are used below.
terms:
  apple:
    ">1": apples
    # default is to fall back to "apple" (the key), or you may add a `default: ` line here
  mango:
    ">1": mangoes
  tooth:
    ">1": teeth
  block:
    ">1": blocks above
    default: block above
    "=-1": block below
    "<-1": blocks below

# no namespace for the plugin needed. The "groups" are only for convenience in internal management and are not strictly required.
group generic: # for groups, you need to specify it is a group, not a translation.
  noPerm:
    value: "<ERROR>You don't have permission to use this command" # An </ERROR> closing tag is optional. The whole value is wrapped inside an <INFO> element.
    description: "This is a special note to translators. This is normally optional. If `value` is the only element, `value: ` can be omitted, , like the following translation"
  specialChars: "<NOTICE>This line contains some special chars such as <EM>&amp</EM>, <EM 2>&lt;</EM> and <EM 2>&gt</EM>, and both<BR>line break and\nnormal line feed are allowed."
  withVars:
    value: "<WARNING>This line uses some variables such as <EM><$first></EM>, <EM><$third 2></EM> and <EM><$second></EM>"
    vars:
      first: "This describes what the $first variable is" # default `type` is "string"
      second:
        type: int
        description: "This describes the $second variable"
      third:
        type: float
        description: "Because it is <$third 2> in the value, it will round to 2 digits behind decimal point.
  myLocation:
    value: "For the <$ord plus=1 ordinal> time you are at <$location>. <WARNING>Note that you are <$location y minus=62 absolute> <%block <$location y minus=62>> sea level."
    # displays "For the 2nd time you are at (1, 90, 3). Note that you are 28 blocks above sea level." if $ord is 1 and $location is `new Vector3(1, 90, 3)`
    vars:
      ord:
        type: int
        description: Number of times the player has been at $location before
      location:
        type: vec3 pos # "pos" is an optional flag that emphasizes that the variable is a position vector, not a relative vector
        description: The current location of the player
  eatFruit:
    value: "You ate <$appleCount> red <%apple $appleCount> and <$mangoCount> yellow <%mango $mangoCount>, so you lost <$teethLost> <%tooth $teethLost>"
    vars:
      appleCount: {type: number} # number is a union of int and float
      mangoCount: {type: int}
      teethLost: {type: int}

Attributes such as plus, y, ordinal etc. only work when the type is declared correctly.

The parameter in <%term> can be any numeric expression, including literal numbers and number/int/float variables. Same for the value in plus= and minus=.

While it can be so complex, for basic users, it can be as simple as:

lang: base
myFirstMessage: "Hi this is a message"
mySecondMessage:
  value: "Hi this is a message containing <$one> <$two> <$three> variables"
  vars: [one, two, three]
myThirdMessage:
  value: "Maybe I <$should> be <$more> translator-friendly?"
    vars:
      should: Some description here
      more: Some description here

Poggit shall provide an even simpler user interface for translators to get around with the formatting, adding different variables with custom alterations.

[TheDiamondYT1]

@SOF3 That looks busy