debian-installer language/country chooser
=========================================

The purpose of languagechooser and countrychooser is to ask the person
doing the installation about his preferred language and country of
"residence".  This information can be used to choose which language and 
country or region to use during installation and set this language and
country as the default language and country after the installation.

This information will be used for building a value for the general system
locale.

This task has been split in two packages:

-languagechooser, which is aimed at choosing a language. This language
 will be chosen among a list of "supported" languages.

 Languagechooser also presets some country-related values for use by
 countrychooser

-countrychooser refines the country choice inherited from
 languagechooser. It allows choosing any "country" in the world. 
 Depending on the language+country combination, 
 this will be used for setting a locale or not (see below for details)

"Language" here means any language Debian has been significantly
translated into. This may be a simple ISO-639 code such as "en" or
"de" or a language "variant" code such as "pt_BR" (Brazilian
Portuguese) or zh_TW (for Traditional Chinese). The tradition of
representing language variants may here be confusing as zh_TW seems to
be "Chinese as spoken in Taiwan" while it is indeed "Traditional
Chinese". Debian has just here kept the most common way to represent
these language flavours.

"Country" here is meant to represent the place the user or the machine
is located. This value will be used for several location-related
settings as well as locale-related settings. The list of countries is
taken from the ISO-3166 standards. The names used are the "common"
names of these countries, as defined in the iso-codes package.

The way both packages collaborate is somewhat complicated and will be
described in details below. The general rationale is about building a
value for the system locale which may be as close as possible of the
"real" locale (language+country). as not all langyage+country
combinations are currently supported in Debian, approximations will
occur in some cases.

The mechanism is the following:
1) propose a language choice
2) propose a "short" list of countries with all countries for which
   this language has a supported locale
3) optionnaly propose the whole list of world countries


This package should behave as follows:

  0. Ask the user to pick one of the available languages.

  1. Change presentation language in debconf.
     (value debconf/language; content=language ISO-639 code plus
      optionnally lmanguage variant, for instance pt_BR)

  2. Set the following variables for later use:
     -debian-installer/language
      LIST of languages in order of
      preference. This will be a succession of several xx_YY values
      where xx is a ISO-639 code or lan,guage and YY is an ISO-3166
      code for country. The list is to be read from left to right
      with the preferred combination at the left
      This is meant to be used as the LANGUAGE varaible later
     -debian-installer/country: 
      This value may be pre-feeded with an ISO-3166 name for a country
      This should be done when only one country has a valid locale
      for the given language. For other languages, with several
      possible countries ("possible" here is "supported by locales"),
      the country must NOT be set by languagechooser
     -debian-installer/locale
      This should be a single entry such as fr_CA
      Each language MUST provide one, which will be the default for this 
      language

      This entry may be modified by countrychooser running after 
      languagechooser
     -debian-installer/fallbacklocale
      This should be similar to the "locale" value. This value will *never*
      change. Countrychooser will set debian-installer/locale to it
      when the chosen country builds an unsupported locale

  3. pass the locale information on to the modules that needs it. This
     locale information will, however, in some cases, be unsupported
     at this time, because it needs to be completed by a country/region
     choice. This latter action is devoted to the countrychooser
     package.

The language code is passed into cdebconf.  The locale, country code 
and priority list of languages are passed to base-config/termwrap 
via the cdebconf database.

The countrychooser package will later refine the choice for the country
part of the locale.

Countrychooser mechanism is the following:

1) If a country code was set by languagechooser
   ("mono country" languages....that is, languages for which only one
     country gives a valid locale)

-always keep the valid locale inherited from languagechooser for
 debian-installer/locale

-present user, at medium priority only, with a screen listing all
 world countries
 This value will see the debian-installer/country value with the ISO-3166
 code of the country. This value will onyl be used as a default for
 location related choices such as the timezone or the mirror

2) If NO country code was set by langaugechooser
   (language with at least two countries with a valid locale
    for this language)

-always prompt the user (high priority) with a *short* list of all
 countries for which a valid locale exists for this language
 THIS LIST IS BUILT AT BUILD TIME for countrychooser, not on the fly
 at install time. It is build only for languages which have a debconf
 translation for countrychooser

 This short list includes an "other" choice.

2a) If the user picks up one of the countries in the short list
    the debian-installer/locale value is CHANGED to language_COUNTRY

2b) If the user picks up the "other" choice
    the debian-installer/locale is set to the "fallback-locale" value
    debian-installer/fallbacklocale

If LANG (locale) and/or LANGUAGE (priority list of language codes) was
passed as arguments to the kernel from the boot prompt, these values
should be used instead of presenting the user with questions.

There have been request for the possibility of editing the priority
list of language codes to use.  This might be done, with debconf
priority 'low' to make sure the question will be invisible for most
users.  I [pere 2003-02-28] do not think this is needed in the general
installation, and will keep it out of the first version.
On 2004-06-07, this hasn't been achieved yet.

Information passed into other modules
-------------------------------------

  cdebconf

   - (List of?) language codes to use when choosing which translation
     to use.  Inserted into the 'debconf/language' debconf template.

  kbd-chooser

   - Selects default keyboard based on the locale selected.  This information
     is passed on to base-config and console-tools.

  choose-mirror

   - The country set in countrychooser is used as a default choice

  base-config

   - Locale and list of language codes to use when choosing
     translations.
   - Timezone restricted list of choices based on the selected country

Interaction with the lowmem package
-----------------------------------

The lowmem package is triggered when the available memory prevents
from using translations, because they eat lot of space on the ramdisk.

For this to achieve, lowmem must preseed the following variables:

languagechooser/language-name : the value of the "English" entry
Then it must:
db_fset languagechooser/language-name seen true

debian-installer/locale : "en_US"

countrychooser/country : "US"
Then it must:
db_fset countrychooser/country-name seen true
db_fset countrychooser/shortlist seen true


With these, the installation will continue with English and USA as
values for language and country and the user will not be prompted for
language and country.

Technical details
-----------------

Languagechooser
---------------

The core of the package are the languagelist/languagelist.l10n files.
For a language to appear in the languagechooser screen it must have entries in both these files.

  languagelist
  ------------
The format if the following:

Language;locale;fallbacklocale;langcode;countrycode;langlist;console-data
 where:

   -Language        =language name, in English
                     It is recommended to refer to ISO-639
   -locale          =default locale
                     xx for languages with multiple countries
                     i.e. languages for which a valid locale may exist
                     with several different countries-->type 1 (see below)
                     xx_YY when only one country code leads to a supported
                     locale-->type 2 (see below)
                     
		     IMPORTANT: using xx alone here is the way to choose
                     whether the countrychooser *short* list will be
                     shown to users
                     If xx_YY is found, users will NOT be prompted for
                     a country at default priority
               
                     You should first check in /usr/share/i18n/SUPPORTED
                     whether one or more countries are supported for this
		     language when building this entry

                     Language translators are requested to closely follow
                     the evolution of locales if their language only uses
                     one country.

   -fallbacklocale  =fallback locale (MUST be valid)
                     This locale will be used in case the user goes to
                     the "other" choice in countrychooser and chooses a
                     country with "unsupported" locale

		     It is recommended to use here the country where
                     the language is most widely spoken

   -langcode        =iso-639 TWO characters language code
                     
                     DO NOT GUESS IT. Please check in the iso-codes
                     and locales packages

   -countrycode     =default value for country choice in countrychoose
                     MUST be a valid ISO-3166 alpha-2 code

                     DO NOT GUESS IT. Please check in the iso-codes
                     package

   -langlist        =colon-separated list of possible fallback languages
                     this will be used in the LANGUAGE variable
                     this DOES NOT be empty

   -console-data    =special options for the console-data package
                     (mostly keyboard or temrinal settings)


