Skip to content

Translation

Jump to bottom
Gareth Latty edited this page May 2, 2020 · 13 revisions

Translation

Every string (bit of text) in the application is defined and described in client/src/elm/MassiveDecks/Strings.elm. Translating the application involves providing a translated version of each string.

Specific Terms

Note the difference between "Players" and "Users". Players play the game, users includes both players and spectators, and is the more general term.

In the code, there is a strict distinction between a "Game" (a single game of MD) and a "Lobby" (a room in which players congregate to play one of more games). In the application, we refer to them both as a "game"—it is simpler and users don't really care about the subtle difference in the concepts.

A play code is a Cardcast-specific thing that specifies a deck on their platform, and is not the same thing as a game code, which allows a user to join a game in Massive Decks.

Unicode

Please use unicode characters as appropriate. E.g: the em-dash (—) (which is particularly awkward to notice in monospaced fonts), real quotes (“”), apostrophes (’) and ellipsis (…).

Likewise, unicode offers us valuable hinting tools to control hyphenation and line breaking:

  • A unicode soft hyphen (\u{00AD}) indicated a good point in a word to break it if needed.
  • A unicode zero-width space (\u{200B}) can do the same thing without a hyphen (hyphens should be preferred, however, assuming that is true for the language generally).
  • For the reverse (no line breaking between words), use a unicode non-breaking space (\u{00A0}).

Making Changes

Before getting to deep into the details: adding the translation to the game itself is somewhat technical. If you struggle with it, please feel free to make an issue and get a developer to help you. That way, you can do the translation itself more simply and a developer can do the work of adding the translation into the game, skipping this section.

The best way to get started is to copy the client/src/MassiveDecks/Languages/En.elm translation. Add the language to the lists in both client/src/MassiveDecks/Languages/Model.elm and client/src/MassiveDecks/Languages.elm (at the top and at the bottom in pack).

e.g: Adding English (Great Britain). The IETF language tag for this is en-GB, so we'll use EnGB as the name.

In client/src/MassiveDecks/Languages/Model.elm:

   type Language
       = En
       ...
       | EnGB -- Add this line.

In client/src/MassiveDecks/Languages.elm:

   import MassiveDecks.Strings.Languages.EnGB as EnGBLang -- Add this line.

   ...

   languages : List Language
   languages =
       [ En
       ...
       , EnGB -- Add this line.
       ]

   ...

   pack : Language -> Translation.Pack
   pack language =
       case language of
           En ->
               EnLang.pack

           ...

           EnGB -> -- Add this line.
               EnGBLang.pack -- Add this line.

This should result in a new language that works exactly as English does. You can now start changing the metadata.

In client/src/MassiveDecks/Languages/EnGB.elm (replacing EnGB with your language, as noted the best way to create this file is to copy an existing language):

   module MassiveDecks.Strings.Languages.EnGB exposing (pack) -- Change the last part (EnGB here) to the same as the file name.

   ...

   pack : Translation.Pack
   pack =
       { code = "en-GB" -- Change this to the IETF language tag for the language.
       , name = English
       , translate = translate
       , recommended = "cah-base-en" |> BuiltIn.Id |> Source.BuiltIn -- Change this if you add a new built-in deck for the language.
       }

You will notice that we also need a string describing the language, and a deck (the Cards Against Humanity base deck) to recommend to users (see the below section on localizing decks)—if there is not a localized deck, you can just continue to recommend the English base deck.

In client/src/MassiveDecks/Strings.elm:

   -- Language Names
   | English -- The name of the English language (no specific dialect).
   ...
   | BritishEnglish -- Add this line.

Note that once you do this, you'll need to add a translation for this to every other language as well.

In client/src/MassiveDecks/Languages/EnGB.elm (replacing EnGB with your language):

  pack : Translation.Pack
  pack =
       { code = "en-GB"
       , name = BritishEnglish -- Change this to your new string.
       , translate = translate
       }

You can now start changing the actual strings. These are created either from raw text or references to other strings:

   MassiveDecks ->
       [ Text "Massive Decks" ]

   WhatIsThis ->
       [ Text "What is ", Ref MassiveDecks, Text "?" ]

This will render was "What is Massive Decks?", but if you changed "MassiveDecks" to "Test", it would result in "What is Test?". This allows you to avoid translating the same thing many times and allows the text to be enhanced with things like links automatically.

In general, you should be able to just translate the raw text in quotes and shuffle things around. The more complex parts should pretty much remain as-is.

Note that some strings take arguments:

  UserConnected { username } ->
       [ Text username, Text " has reconnected to the game." ]

Note that some arguments are numbers, and these have to be converted to strings:

   Score { total } ->
       [ Text (String.fromInt total) ]

Note this is code, rather than configuration, so complex operations can be performed. Plural is an example of this, as is asWord. If you are not a programmer, these may be awkward - please feel free to explain the behaviour you need in a bug to get a developer to help out for awkward cases like different grammar rules for plurals, etc...

Decks

Decks aren't globally localized as it is unclear how that would function as the game can often rely on wordplay that may not translate. As such, all players in a game must agree on the decks to be used in whatever language they are.

However, it is possible to provide localized versions of decks as different decks, and to suggest appropriate versions in the UI.

Decks present a much harder localization task than the UI: fundamentally the cards are jokes, and so translating them is not a simple case of direct translation. If we look at official Cards Against Humanity localized versions—while some cards are direct translations—a lot of references are replaced with locally appropriate versions. This is most clear in the various English language versions of the game, where the British and Canadian versions have many cards wholesale replaced (CAH claim about 15%). Even where a card is translated as a concept, the exact wording should aim to be as comedic as possible in the target language, while retaining the grammatical fit for the game to work. As such, there is a great deal of artistic license to an "accurate" localization.

Decks are stored on the server, not the client, and so use an entirely different system to the UI localization. In general, it is a simpler, easier format. Please see the built-in decks page for details on the format.

Clone this wiki locally