Update for Timezone Changes

This instruction is out of date. After CLDR 27, <variable> items for tzid in supplmentalMetadata.xml were deprecated (removed). We use bcp47/timezone.xml as the master reference for the valid tzids in CLDR. I filed a new ticket to develop a new tool comparing tzids in timezone.xml with the tz database, and update this instruction. (Yoshito Umaoka, 2015-08-25)


Instructions updated 12-12-2012 by J. C. Emmons

Do the following to update to a new timezone database. In the instructions: {cldr} refers to your base directory where your SVN working copy of CLDR is located.

  1. Download the latest version of the data from http://www.iana.org/time-zones
    • The file you care about will look like tzdata2012j.tar.gz (with perhaps different year/letter)
    • Unpack, and copy contents into {cldr}\tools\java\org\unicode\cldr\util\data
    • Edit the file {cldr}\tools\java\org\unicode\cldr\util\data\tzdb-version.txt to change the version, eg for the file tzdata2012j.tar.gz, the version is 2012j.
    • Do an "svn status".  You can throw away any of the files that aren't currently in SVN, ( i.e. lines beginning with '?' ),  such as "Makefile", "solar*", "yearistype.sh", "iso3166.tab", etc. Note that 'backward' files is included, but CLDR does not use 'backzone', 'zone.tab' is included, but CLDR does not use 'zone1970.tab'. So throw away 'backzone' and 'zone1970.tab'.
    • If you are using Eclipse, remember to refresh the project.
  2. Diff zone.tab with SVN. ( svn diff zone.tab )
    • if any IDs in zone.tab changed name, add the mapping to org.unicode.cldr.util.ZoneParser.FIX_UNSTABLE_TZID_DATA
    • The format is <new name>, <old name>
      • Eg {"America/Argentina/Buenos_Aires", "America/Buenos_Aires"},
  3. Now Verify
    • Run org.unicode.cldr.tool.GenerateSupplementalZoneData to generate new data.
    • Paste the <variable id="$tzid" type="choice"> ... </variable>  into supplementalMetadata.xml
    • CAREFULLY COMPARE THE RESULTS TO THE LAST VERSION
    • Any new zone.tab ID must show up, eg.
      • supplementalMetadata.xml, new: Australia/Eucla
  4. Check for REMOVED IDs. This doesn't happen very often, but requires some real thought when it does.
    • If there are any $tzid's that are in the last version that are not in the current,
    • find out what "real" alias it should point to. There are 2 types.
    • 1. ID was removed completely, like HST. In that case, there will be no item or alias in zoneItem's.
      • Look at the old supplemental data to determine what it used to map to (eg Pacific/Honolulu)
      • Add to supplementalMetaData
        • <zoneAlias type="HST" replacement="Pacific/Honolulu"/>
      • Add ZoneParser.ADD_ZONE_ALIASES_DATA
        • eg {"HST", "Pacific/Honolulu"},
      • Rerun  GenerateSupplementalZoneData  + cut/paste into supplementalMetadata.xml
    • 2. ID is no longer in zone.tab (after fixing "A"), but is still linked.
      • Add to supplementalMetadata. Use the zoneItem info
        • <zoneAlias type="Africa/Timbuktu" replacement="Africa/Bamako"/>
      • Add to ZoneParser.FIX_DEPRECATED_ZONE_DATA. Example:
        • "Africa/Timbuktu",
      • Rerun GenerateSupplementalZoneData  + cut/paste into supplementalMetadata.xml
      • Sometimes the aliases will be on the wrong element. If so, add to org.unicode.cldr.util.ZoneParser.PREFERRED_BASES.
  5. Repeat C and D until no changes occur.
    • When you are all done, there should ONLY be additions to $tzid
  6. Update <variable id="$timezone_XXX"...> in supplementalMetadata.xml. This is generated by CountItem tool. See Update Language/Script/Region Subtags for more details.
  7. Add new ID to bcp47/timezone.xml
    • Short ID is based on UN/LOCODE
    • When location name used by the new zone ID is not a city, read the description in the tz database and select the most appropriate location using the zone. For example, Bougainville (Pacific/Bougainville) is the name of islands / province in Papua New Guinea. There is no LOCODE available for the location. According to the description in the tz database, the zone applies to Arawa-Kieta region. Arawa is the capital and the largest town in the province, and has a LOCODE "PG RAW". Therefore, the short ID "pgraw" is assigned.
    • If a zone ID is associated with a location, but no appropriate LOCODE is available, define a new short ID other than 5 letters, with first 2-letter indicating the ISO 3166 alpha 2 code, in lower case letters. For example, "debsngn" for Europe/Busingen.
    • If a zone ID is not for a political region, then define a new short ID other than 5 letters in lower case letters. For example, "cst6cdt" for CST6CDT.
    • The canonical tz database ID should be the first value of alias= attribute. (It is unlikely that a new zone ID has other aliases.)
    • Add since= attribute specifying the next major CLDR release, for example, since="27
  8. Update supplemental/metazoneInfo.xml.
    • For any of the timezones that are added, changed, or deleted, you will need to make the appropriate metazone updates to supplemental/metazoneInfo.xml.
    • For each zone, you will need to read the Olson TZ data file ( they are grouped by continent ), and compute the transition times ( in GMT, not local time ) for any metazone transitions.  A metazone transition usually occurs when the abbreviation changes, for example, from E%sT to C%sT.  If a zone is simply starting or stopping observence of DST, then usually no metazone transition is necessary.  Example, going from E%sT to EST is NOT a metazone transition.
  9. Update windowsZones.xml
    • <TODO> Updating and verifying windows zone mapping currently depends on ICU tooling (icuapps/trunk/WinTZ). This process should be integrated to CLDR tooling in future. Detailed steps will be provided later.
  10. Record the latest version that's been synced as a meta-data//This is new (Aug 2020)!
  11. Check in the new supplemental files and the data files in ...org\unicode\cldr\util\data
    1. just the data files that are already checked in (eg check in 'africa', but not 'factory')
  12. Do Regenerate Charts
Comments