# Documents for developers

## Translation (I18N) guide

Author: Nicolas Boichat <nicolas -at- boichat.ch>

Do you want to translate ddccontrol to your favorite language? Then, this guide is for you!

The distribution is split in two packages: `ddccontrol` (the main program), and `ddccontrol-db` (monitor database).

Tools you need: `git`, `automake`/`autoconf`, `gettext`, `make`, `poedit` (or another tool, or a simple text editor).

First, you need to check out the sources from the Git repositories: ddccontrol and ddccontrol-db.

Note you need to perform the following operations in both the ddccontrol and ddccontrol-db repositories (there are strings to translate in the main program, and in the database).

Then run:

    # ./autogen.sh
    # ./configure (maybe you will need some devel package to make it working)
    # cd po
    # make update-po

If the po file for your language doesn't exist, simply copy `ddccontrol.pot` to `LANG.po` (for example, for French, it is `fr.po`) and update the fields in it (like `AUTHOR`, `CHARSET`, etc...)

Then open your `.po` file, and translate the strings! I recommend that you use a tool like poedit, as it warns you visually when strings are wrong, and offers spellcheck. But it's your choice .

When you are finished, it would be nice to test if it works by installing and running the software, but it is not mandatory, particularly if you don't have the needed hardware (i.e. a monitor supporting DDC/CI). Then, sending the completed `.po` files through a pull request or issue on the ddccontrol project on GitHub.

It is a good idea to follow the GitHub project, particularly if you have problems translating some technical strings. Please use the GitHub project issue tracker or pull request discussion for such questions, so the same terms do not need to be explained repeatedly to all translators.

Also, if you encounter mistakes in the original English strings, please report those as well.

List of languages with active translators:

- French: Nicolas Boichat
- Russian: Sergei Epiphanov

I hope my explanations were complete, otherwise do not hesitate to contact me (cc-ing the devel list) if you have questions.

THANK YOU.

## Monitor database structure

The monitor database is written in XML, it can be found in the `db` directory of `ddccontrol-db` package.

This directory contains the following files:

- `options.xml`
- `monitor/`%monitor_id%`.xml`

### Control list

XML file: `options.xml`

`control` elements (e.g. `brightness`) are contained in `group` elements (e.g. `color settings`). `group` and `subgroup` elements allow the GUI to separate the controls in different branches on the tree.

`options` attributes:

- `date`: indicates the release date of the current database (YYYYMMDD format).
- `dbversion`: indicates which version of database format is used (must be set to 3).

`group` attributes:

- `name`: full English group name.

`subgroup` attributes:

- `name`: full English subgroup name.
- `pattern`: name of the fullscreen pattern `gddccontrol` must display to help the user to adjust subgroup's controls (optional). For possible values, see `ddccontrol/src/gddccontrol/fspatterns.c`.

`control` attributes:

- `id`: abbreviated control name.
- `name`: full English control name.
- `address`: DDC/CI address (optional).
- `type`: one of these values:
  - `value`: The control accepts values in a continuous range (e.g. brightness).
  - `command`: An action occurs when the value is set to something greater than `0` (e.g. degauss). If you don't define any `value` element in a command control, the default value `0x01` will be used.
  - `list`: The control accepts a list of values (e.g. OSD language).
- `refresh` (only for list and command controls): Set whether other controls must be refreshed after changing list value or running the command associated with the control (optional). Possible values:
  - `none`: Do not refresh anything. (default)
  - `all`: Refresh all controls.

`value` attributes:

- `id`: abbreviated value name.
- `name`: full English value name (it is not needed if there is only one value for command controls).
- `value`: DDC/CI control value (optional).

File format:

    <?xml version="1.0"?>
    <options date="%date%" dbversion="3">
      <group name="%groupname%">
        <subgroup name="%subgroupname%" pattern="%patternname%">
          <control id="%control_id%" type="value" name="%control_name%" address="%hex_address%"/>
            <!-- Command using the default 0x01 address -->
          <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%"/>
          <control id="%control_id%" type="command" name="%control_name%" address="%hex_address%">
            <value id="%value_id%" value="%hex_value%"/>
          </control>
          <control id="%control_id%" type="list" name="%control_name%" address="%hex_address%">
            <value id="%value_id%" name="%value_name%" value="%hex_value%"/>
            <value...>
          </control>
          <control ...>
        </subgroup>
      </group>
      <group ...>
    </options>

### Monitor Profiles

XML files: `monitor/`%monitor_id%`.xml`

#### `caps` element

The caps attribute is optional. Its format is defined in ACCESS.bus specifications.

To add controls to caps, use the `add` attribute. To remove controls from caps, use the `remove` attribute.

Note remove is handled before add, so if you remove and add a same control, it will finally be in caps.

#### `controls` element

List of controls supported by a monitor (optional if you have an `include` element).

`control` `id` attributes are defined in `options.xml`. If `control` `type` is `list` or `command` without default values, supported values must be defined.

`address` attribute for `control` elements and `value` attribute for `value` elements are optional if they are defined in the general options file.

The `init` attribute in `monitor` element define the type of the initialization: DDC/CI standard (`standard`), or Samsung (`samsung`). This attribute is optional, as long as the monitor profile includes another profile which defines this attribute.

You can set a `delay` attribute in `control` elements to set the time in milliseconds to wait after changing the value of this control. If you don't, a default value is used.

#### `include` element

Includes another monitor, manufacturer or standard profile, specified by the `file` attribute.

Monitor profile are read sequentially. Control and init mode redifinitions are ignored, so define specific controls and init mode before including a generic profile. Caps are also treated sequentially, so if a control is not in CAPS at the time it is defined, it won't be supported by ddccontrol.

File format:

    <?xml version="1.0"?>
    <monitor name="%full_monitor_name%" init="[standard|samsung]">
      <caps add="%add_caps%" remove="%remove_caps%"/>
      <controls>
        <!--- value -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
        <!--- command using a default 0x01 value-->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%"/>
        <!--- command -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
          <value id="activate" value="%hex_value%"/>
        </control>
        <!--- list -->
        <control id="%control_id%" address="%hex_address%" delay="%wait_time%">
          <value id="%value_id%" value="%hex_value%"/>
          <value...>
        </control>
        <control...>
      </controls>
      <!--- Including VESA generic profile is generally a good idea. -->
      <include file="VESA"/>
    </monitor>

If a monitor supports exactly the same controls as another one, you can define it as shown:

    <?xml version="1.0"?>
    <monitor name="%full_monitor_name%">
      <caps add="%add_caps%" remove="%remove_caps%"/>
      <include file="%include_monitor_id%"/>
    </monitor>

## Profile file structure

Profile files are used to save the value of some controls.

`profile` attributes:

- `pnpid`: indicates the PNP id of the monitor that this profile applies to.
- `name`: profile name.
- `version`: indicates which version of profile format is used (must be set to 1).

`control` attributes:

- `address`: DDC/CI address of the control.
- `value`: DDC/CI control value.

File format:

    <?xml version="1.0"?>
    <profile pnpid="%pnp_id%" name="%profile_name%" version="1">
      <control address="%hex_address%" value="%control_value%"/>
      <control...>
    </profile>