Editing Translation

{{TOCRIGHT}}
== Introduction ==

Blood Omnicide support translation packs in the form of separate [[PK3 | PK3 files]]. This article will explain how to edit them, creating your own localization pack.

Translation packs follows this rules:

* Translate texts, textures, sounds, everything

* Language can be chosen without quitting the game

* More translation packs should be created to allow support for more languages

== Names ==

Standart naming for locale file is '''L-localename0.PK3''', where localename is language identificator.

Example: localname is "espanol" and pack name will be '''L-espanol0.PK3'''.

A number in the end is used to break up locale to separate PK3 files (or make update pack later), engine reads them in the order: '''L-espanol0.PK3''', '''L-espanol1.PK3''', '''L-espanol2.PK3''' etc.

== Text encoding ==

All text files should use Unicode (UTF-8) encoding with no BOM (Byte-Order-Mark). National encodings (ones Windows Notepad uses) are not suppored.

Tools to edit text files in UTF-8:
* [http://notepad-plus-plus.org/ Notepad++]
* [http://akelpad.sourceforge.net AkelPad]

== Contents of translation pack ==

* '''kain''' - base folder
** '''locales'''
*** ''localename.nsx'' - heading locale script
*** ''localename.tga'' - а picture to show in the locale selection menu
*** '''locale/''' - general locales folder
**** '''localename/''' - base locale folder
**** '''fonts/''' - font definition files and font faces (see [[NSX_(QFont) | QFONT files]])
**** '''gfx/''' - replacements for UI textures (kain/gfx).
**** '''models/''' - replacements for model textures (kain/models).
**** '''speech/''' - replacements for speech sounds (kain/sound/speech).
**** '''strings/''' - all translation strings in the form of INI files (see [[NSX | NSX files]])
***** ''characters.nsx'' - [[NSX (Translation string files) | translation strings]] for character names
***** ''credits.nsx'' - translation strings for credits
***** ''gameover.nsx'' - translation strings for game over screen
***** ''gamestats.nsx'' - translation strings for game stats
***** ''mapnames.nsx'' - translation strings for map names (keys are filenames under kain/maps, values are names)
***** ''menu.nsx'' - translation strings for menus
***** ''prestige.nsx'' - translation strings for prestige status
***** ''speech.nsx'' - translation strings for speech
**** '''video/'''- subtitles translation for FMV' (see [[DPSUBS | DPSUBS files]])
**** '''textures/''' - replacements for map textures (kain/textures).
**** ''ui.ns2'' - user interface function (contains a numbering and date functions)

== How to make a translation ==

# Download sample pack;
# Unpack it so you will have access to all files
# Rename it to your language
# Find .TTF/.OTF fonts that matches your language and place them to the pack (replace default fonts);
# Translate all strings files (.nsx);
# Translate cinematics subtitles (.dpsubs)
# Translate ui.ns2;
# Create translated worldmap tile
# Create a picture to show in the locale selection menu;
# Edit heading locale script (set author and version);
# (Optional) Add replacement speech sound files files
# (Optional) Add cinematics sound override files
# Make a [[PK3]] file;

== Translating speech ==

=== How speech scripts works ===

Speeches are activated by a game scripts which calls a ''character'':''group'':''key'' name to be played. Characters are defined in <locale>/strings/characters.nsx file (also can be defined in any other .nsx file under <locale>/strings/ in the [character] group). Groups are speech groups, defined inside NSX files in the ''[speech_<groupname>]'' style. There are separate groups for kain monologues, scene speech, gossip etc. Keys are key name inside speech groups, a value given to that key sets a text for speech.

Character+Grops+Keys form an unique speech, which have a text (a value of key) and matching sound file. The sound file path is expected to be: <basepath>/key.ogg or / <speechbase>/key.wav. The ''basepath'' is a basepath for speech files which are set per-character in the [speech] group (defined in very top of speech.nsx). For example, basepath for speech of kain character is 'speech/kain/'.

Example:

 [speech]
 kain=speech/kain/

 [speech_kain]
 aver1=The gate of Avernus opened slowly before me, daring me to cross the threshold.<5.5>Who was I to reject such an invitation?<9>
 aver2=Avernus consumed itself before my eyes. There seemed no easy path to gain entry to the hell laid out before me.<8.5>Perhaps there was a way inside from above the chaos that reigned there.<13>

This file defines two speeches:
* kain:kain:aver1 - points to speech/kain/aver1
* kain:kain:aver2 - points to speech/kain/aver2

=== The speech text ===
Speech text are subtitles text, which also should have ''gaps'' to break speech in several parts to be played in sequence. it is important to break speech text into a parts as blood omen have some very large speech files, more than 50 seconds, which will take a half-screen for a text if shown all at once.

The gaps are set in **<seconds>** tags, where ''seconds'' is a time, when text after <>-tag will be displayed. The last <seconds> tag sets a length of whole speech, so if speech sound file get missing, speech are displayed anyway.

Example:

 aver1=The gate of Avernus opened slowly before me, daring me to cross the threshold.<5.5>Who was I to reject such an invitation?<9>

This breaks aver1 speech into 2 parts:
* ''The gate of Avernus opened slowly before me, daring me to cross the threshold.''
* ''Who was I to reject such an invitation?'' (starts at 5.5 seconds).
The whole length of speech is 9 seconds.

=== Different game versions ===

There are some spechal groups which is used to override the speech files based on current game version.

The [!PlayStation!] groups sets the speech keys whil will override default pc speech in playstation version of the game. It is proven that playstation version have some speech shortened and [!PlayStation!] groups lets it have adequate subtitles. The systax of speech in [!PlayStation!] group are ''group_key''.

=== Testing speech in game ===

==== Re-load locale ====
{{cmd|menu_restart| [[console]] command to restart menu system and re-load the current locale.}}

When editing locale strings on-the-fly, use this command to force reload strings in order for changes to take effect.

==== Play particular speech ====
{{cmd|speech <action> <character> <group> <key> [wait_after_played] [delay_before_played] | [[console]] command helps to test any speech}}

Actions are:
*say - standart speech
*notice- heared 'in head of player', used fro someone's comments etc.
*overhead - npc talk (yellow text)

Examples:
 speech say kain armor_desc 0
 speech say kain kain aver1
 speech say rogue gossip coor3

{important|when editing speech.nsx on the fly, call the menu_restart command in the game for tha changes to take effect}}

==== Testing a whole locale ====
{{cmd|testlocale <localename> [vs localename] | [[console]] command helps to test whole locale for missing or extra strings.}}

''localename'' is name of locale to be tested. 'vs localename' additional arg can be supplied to test agains non-default locale (like testign ru-ru vs fr-fr).

Examples:
 testlocale fr-fr
 textlocale fr-fr vs ru-ru

Example of command output:
 string missing: '[speech_guardian] dej2' (locale/default/strings/speech.nsx:435)
 extra string: '[!PlayStation!] [speech_guardian_bane3]' (locale/ru-ru/strings/speech.nsx:561) - not defined in 'default' locale

== Sample locale packs ==
Here is the list of reference locale packs that you can use as a base:

''' Blood Omnicide v0.1 NEW SPEECH LAYOUT  '''

:English: [http://omnicide.legacy-of-kain.ru/files/omnicide/0.1/locales/L-default0.PK3 download]

''' Blood Omnicide Demo ''' (Using old translation layout)
:English: [http://omnicide.legacy-of-kain.ru/files/omnicide/demo/locales/L-default0.PK3 download]

:Russian: [http://omnicide.legacy-of-kain.ru/files/omnicide/demo/locales/L-ru-RU0.PK3 download]

:Espanol: [http://omnicide.legacy-of-kain.ru/files/omnicide/demo/locales/L-es_ES0.PK3 download]

{{finished}}