CLDR-18960 Add README.md files in common/* directories (#5213)

btangmu · web-flow · commit e17984e161a5 · 2025-12-16T13:04:52.000-05:00
diff --git a/common/README.md b/common/README.md
@@ -2,4 +2,6 @@
 
 This directory contains CLDR data corresponding to the release.
 
+CLDR data files are interpreted according to the [LDML specification](https://unicode.org/reports/tr35/).
+
 For copyright, terms of use, and further details, see the top [README](../README.md).
diff --git a/common/annotations/README.md b/common/annotations/README.md
@@ -1,5 +1,5 @@
 # CLDR `common/annotations` directory
 
-This directory contains annotations and TTS names for characters.
+This directory contains XML data files with annotations and TTS (text-to-speech) names for characters.
 
 For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/annotationsDerived/README.md b/common/annotationsDerived/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/annotationsDerived` directory
+
+This directory contains XML data files with short names and annotations derived using `GenerateDerivedAnnotations.java`.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/bcp47/README.md b/common/bcp47/README.md
@@ -0,0 +1,6 @@
+# CLDR `common/bcp47` directory
+
+This directory contains XML data files related to [BCP (Best Current Practice) 47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt)
+and the [LDML specification](https://unicode.org/reports/tr35/).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/casing/README.md b/common/casing/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/casing` directory
+
+This directory contains XML data files with casing information generated by CasingInfo.java.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/collation/README.md b/common/collation/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/collation` directory
+
+This directory contains XML data files with collation information related to `CoreCoverageInfo.java` and `ChartCollation.java`.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/dtd/README.md b/common/dtd/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/dtd` directory
+
+This directory contains DTD and other data files. See the [LDML specification](https://unicode.org/reports/tr35/).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/main/README.md b/common/main/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/main` directory
+
+This directory contains the main XML data files for the CLDR project. For example, fr_CA.xml contains data for Canadian French.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/rbnf/README.md b/common/rbnf/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/rbnf` directory
+
+This directory contains XML data files related to the Rule-Based Number Format (RBNF).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/segments/README.md b/common/segments/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/segments` directory
+
+This directory contains XML data files related to segmentations. See [Segmentations](https://unicode.org/reports/tr35/tr35-general.html#Segmentations).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/subdivisions/README.md b/common/subdivisions/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/subdivisions` directory
+
+This directory contains XML data files related to territory subdivisions.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/supplemental-temp/README.md b/common/supplemental-temp/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/supplemental-temp` directory
+
+This directory contains an XML data file used for testing. See [CLDR-15548](https://unicode-org.atlassian.net/browse/CLDR-15548).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/supplemental/README.md b/common/supplemental/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/supplemental` directory
+
+This directory contains various supplemental XML data files.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/testData/README.md b/common/testData/README.md
@@ -0,0 +1,7 @@
+# CLDR `common/testData` directory
+
+This directory contains data for testing expected behavior of CLDR operations.
+
+The format may vary between folders or files.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/testData/_readme.txt b/common/testData/_readme.txt
diff --git a/common/testData/datetime/README.md b/common/testData/datetime/README.md
@@ -1,25 +1,26 @@
-# Test Data for DateTime Formatting
+# CLDR `common/testData/datetime` directory
 
 This directory contains test data for DateTime formatting.
+
 This data is the result of the test data generator `GenerateDateTimeTestData.java`.
 
 The design of the test generator is to provide the "expected value" of datetime formatting over several dimensions,
-such as locale,
-formatting options (date length, calendar, etc.), 
-and various input datetime values.
+such as locale, formatting options (date length, calendar, etc.), and various input datetime values.
 
 The test generator constructs the expected value using the various pieces
 (date format pattern, time format pattern, datetime "glue" pattern)
 and `SimpleDateFormat`s to combine them together.
 Each test case reports the inputs for the test case and the expected value.
 
-The UTS 35 LDML spec for datetime formatting will be updated in CLDR v48 to specify
-that the default value for dateTimeFormatType will be "atTime".
+The UTS 35 LDML spec for datetime formatting was updated in CLDR v48 to specify
+that the default value for dateTimeFormatType is "atTime".
 dateTimeFormatType represents the value that indicates the type of
 datetime "glue" pattern, ex: indicating "atTime" or "standard" pattern.
 By datetime "glue" pattern, we mean the pattern that is used to combine the result
 of date-only formatting and time-only formatting to arrive at the overall combined
 formatting for the datetime object containing both a date and a time.
 Therefore, for test cases in the dataset in which a date and a time are both present
 in the datetime object, if a dateTimeFormatType is not specified explicitly, the
-value should be assumed to be "atTime".
+value should be assumed to be "atTime".
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/localeIdentifiers/README.md b/common/testData/localeIdentifiers/README.md
@@ -0,0 +1,15 @@
+# CLDR `common/testData/localeIdentifiers` directory
+
+This directory contains test data for grapheme locale validity, canonicalization, and name generation.
+
+The format may vary between folders or files.
+
+Format:
+
+Generally has the following structure, but the values depend on the file.
+
+`@<parameter>=<parameter value>`
+
+`<input> ; <expected output>`
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/localeIdentifiers/_readme.txt b/common/testData/localeIdentifiers/_readme.txt
diff --git a/common/testData/messageFormat/README.md b/common/testData/messageFormat/README.md
@@ -1,3 +1,7 @@
+# CLDR `common/testData/messageFormat` directory
+
+This directory contains test data for grapheme locale validity, canonicalization, and name generation.
+
 The tests in the `./tests/` directory were originally copied from the [messageformat project](https://github.com/messageformat/messageformat/tree/11c95dab2b25db8454e49ff4daadb817e1d5b770/packages/mf2-messageformat/src/__fixtures)
 and are here relicensed by their original author (Eemeli Aro) under the Unicode License.
 
@@ -68,6 +72,7 @@ The function `:test:function` requires a [Number Operand](/spec/registry.md#numb
 #### Options
 
 The following _options_ are available on `:test:function`:
+
 - `decimalPlaces`, a _digit size option_ for which only `0` and `1` are valid values.
   - `0`
   - `1`
@@ -174,3 +179,5 @@ except that it cannot be used for selection.
 
 When `:test:format` is used as a _selector_,
 the steps under 2.iii. of [Resolve Selectors](/spec/formatting.md#resolve-selectors) are followed.
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/personNameTest/README.md b/common/testData/personNameTest/README.md
@@ -0,0 +1,7 @@
+# CLDR `common/testData/personNameTest` directory
+
+This directory contains test data for personName formats.
+
+The format may vary between folders or files.
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/personNameTest/_readme.txt b/common/testData/personNameTest/_readme.txt
diff --git a/common/testData/segmentation/graphemeCluster/README.md b/common/testData/segmentation/graphemeCluster/README.md
@@ -0,0 +1,9 @@
+# CLDR `common/testData/graphemeCluster` directory
+
+This directory contains test data for grapheme cluster testing generation.
+
+Format:
+
+`<source string> ; <copy of source string with ÷ inserted at boundaries>`
+
+For copyright, terms of use, and further details, see the top [README](../../../../README.md).
diff --git a/common/testData/segmentation/graphemeCluster/_readme.txt b/common/testData/segmentation/graphemeCluster/_readme.txt
diff --git a/common/testData/transforms/README.md b/common/testData/transforms/README.md
@@ -0,0 +1,9 @@
+# CLDR `common/testData/transforms` directory
+
+This directory contains test data for testing transforms.
+
+Format: uses tab delimiters to make it easier to read into spreadsheets
+
+`<source text><TAB><expected result text>`
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/transforms/_readme.txt b/common/testData/transforms/_readme.txt
diff --git a/common/testData/units/README.md b/common/testData/units/README.md
@@ -0,0 +1,7 @@
+# CLDR `common/testData/units` directory
+
+This directory contains test data for units: conversions and preferences.
+
+The format may vary between folders or files.
+
+For copyright, terms of use, and further details, see the top [README](../../../README.md).
diff --git a/common/testData/units/_readme.txt b/common/testData/units/_readme.txt
diff --git a/common/transforms/README.md b/common/transforms/README.md
@@ -0,0 +1,5 @@
+# CLDR `common/transforms` directory
+
+This directory contains XML data files related to transforms.
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/uca/README.md b/common/uca/README.md
@@ -0,0 +1,7 @@
+# CLDR `common/uca` directory
+
+This directory contains text (`.txt`) files related to the Unicode Collation Algorithm (UCA).
+
+For a description of the format and usage, see [Root Collation Data Files](https://www.unicode.org/reports/tr35/tr35-collation.html#Root_Data_Files).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/common/validity/README.md b/common/validity/README.md
@@ -0,0 +1,7 @@
+# CLDR `common/validity` directory
+
+This directory contains XML data files, which may be automatically generated.
+
+See [Update Validity XML](https://cldr.unicode.org/development/updating-codes/update-validity-xml).
+
+For copyright, terms of use, and further details, see the top [README](../../README.md).
diff --git a/tools/cldr-code/src/main/java/org/unicode/cldr/util/CLDRTransforms.java b/tools/cldr-code/src/main/java/org/unicode/cldr/util/CLDRTransforms.java
@@ -14,6 +14,7 @@
 import com.ibm.icu.text.UnicodeFilter;
 import com.ibm.icu.util.ICUUncheckedIOException;
 import java.io.File;
+import java.io.FilenameFilter;
 import java.io.IOException;
 import java.io.Writer;
 import java.util.Arrays;
@@ -109,8 +110,14 @@ public static void registerCldrTransforms(
         Transliterator.registerAny(); // do this last!
     }
 
+    private static class XmlFilter implements FilenameFilter {
+        public boolean accept(File dir, String name) {
+            return name.endsWith(".xml");
+        }
+    }
+
     public static List<String> getAvailableIds() {
-        return Arrays.asList(new File(TRANSFORM_DIR).list());
+        return Arrays.asList(new File(TRANSFORM_DIR).list(new XmlFilter()));
     }
 
     public Set<String> getOverriddenTransliterators() {
