Add placeholder normalization to converter utilities

Introduces convert_with_normalization and convert_auto_with_normalization functions to optionally normalize iOS-style placeholders (e.g., %@, %1$@, %ld) to canonical forms before serialization. Updates documentation and tests to demonstrate usage. Also improves Codec API docs with usage examples for placeholder validation and normalization.

Author: WendellXY

langcodec/src/codec.rs

@@ -625,6 +625,23 @@ impl Codec {
     /// - For each key, each language must have the same placeholder signature.
     /// - For plural entries, all forms within a language must share the same signature.
     /// - iOS vs Android differences like `%@`/`%1$@` vs `%s`/`%1$s` are normalized.
+    ///
+    /// Example
+    /// ```rust
+    /// use langcodec::{Codec, types::{Entry, EntryStatus, Metadata, Resource, Translation}};
+    /// let mut codec = Codec::new();
+    /// let en = Resource{
+    ///     metadata: Metadata{ language: "en".into(), domain: String::new(), custom: Default::default() },
+    ///     entries: vec![Entry{ id: "greet".into(), value: Translation::Singular("Hello %1$@".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
+    /// };
+    /// let fr = Resource{
+    ///     metadata: Metadata{ language: "fr".into(), domain: String::new(), custom: Default::default() },
+    ///     entries: vec![Entry{ id: "greet".into(), value: Translation::Singular("Bonjour %1$s".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
+    /// };
+    /// codec.add_resource(en);
+    /// codec.add_resource(fr);
+    /// assert!(codec.validate_placeholders(true).is_ok());
+    /// ```
     pub fn validate_placeholders(&self, strict: bool) -> Result<(), Error> {
         use std::collections::HashMap;
         use crate::placeholder::signature;
@@ -698,6 +715,8 @@ impl Codec {
 
     /// Collect placeholder issues without failing.
     /// Returns a list of human-readable messages; empty if none.
+    ///
+    /// Useful to warn in non-strict mode.
     pub fn collect_placeholder_issues(&self) -> Vec<String> {
         use std::collections::HashMap;
         use crate::placeholder::signature;
@@ -752,6 +771,19 @@ impl Codec {
 
     /// Normalize placeholders in all entries (mutates in place).
     /// Converts iOS patterns like `%@`, `%1$@`, `%ld` to canonical forms (%s, %1$s, %d/%u).
+    ///
+    /// Example
+    /// ```rust
+    /// use langcodec::{Codec, types::{Entry, EntryStatus, Metadata, Resource, Translation}};
+    /// let mut codec = Codec::new();
+    /// codec.add_resource(Resource{
+    ///     metadata: Metadata{ language: "en".into(), domain: String::new(), custom: Default::default() },
+    ///     entries: vec![Entry{ id: "id".into(), value: Translation::Singular("Hello %@ and %1$@".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
+    /// });
+    /// codec.normalize_placeholders_in_place();
+    /// let v = match &codec.resources[0].entries[0].value { Translation::Singular(v) => v.clone(), _ => unreachable!() };
+    /// assert!(v.contains("%s") && v.contains("%1$s"));
+    /// ```
     pub fn normalize_placeholders_in_place(&mut self) {
         use crate::placeholder::normalize_placeholders;
         use crate::types::Translation;

langcodec/src/converter.rs

@@ -9,6 +9,7 @@ use crate::{
     formats::{
         AndroidStringsFormat, CSVFormat, FormatType, StringsFormat, TSVFormat, XcstringsFormat,
     },
+    placeholder::normalize_placeholders,
     traits::Parser,
     types::Resource,
 };
@@ -143,14 +144,135 @@ pub fn convert<P: AsRef<Path>>(
     }
 
     // Read input as resources
-    let resources = match input_format {
+    let mut resources = match input_format {
         FormatType::AndroidStrings(_) => vec![AndroidStringsFormat::read_from(&input)?.into()],
         FormatType::Strings(_) => vec![StringsFormat::read_from(&input)?.into()],
         FormatType::Xcstrings => Vec::<Resource>::try_from(XcstringsFormat::read_from(&input)?)?,
         FormatType::CSV => Vec::<Resource>::try_from(CSVFormat::read_from(&input)?)?,
         FormatType::TSV => Vec::<Resource>::try_from(TSVFormat::read_from(&input)?)?,
     };
 
+    // Ensure language is set for single-language inputs if provided on input_format
+    if let Some(l) = input_format.language().cloned() {
+        for res in &mut resources {
+            if res.metadata.language.is_empty() {
+                res.metadata.language = l.clone();
+            }
+        }
+    }
+
+    // Helper to extract resource by language if present, or first one
+    let pick_resource = |lang: Option<String>| -> Option<Resource> {
+        match lang {
+            Some(l) => resources.iter().find(|r| r.metadata.language == l).cloned(),
+            None => resources.first().cloned(),
+        }
+    };
+
+    match output_format {
+        FormatType::AndroidStrings(lang) => {
+            let resource = pick_resource(lang);
+            if let Some(res) = resource {
+                AndroidStringsFormat::from(res).write_to(&output)
+            } else {
+                Err(Error::InvalidResource(
+                    "No matching resource for output language.".to_string(),
+                ))
+            }
+        }
+        FormatType::Strings(lang) => {
+            let resource = pick_resource(lang);
+            if let Some(res) = resource {
+                StringsFormat::try_from(res)?.write_to(&output)
+            } else {
+                Err(Error::InvalidResource(
+                    "No matching resource for output language.".to_string(),
+                ))
+            }
+        }
+        FormatType::Xcstrings => XcstringsFormat::try_from(resources)?.write_to(&output),
+        FormatType::CSV => CSVFormat::try_from(resources)?.write_to(&output),
+        FormatType::TSV => TSVFormat::try_from(resources)?.write_to(&output),
+    }
+}
+
+/// Convert like [`convert`], with an option to normalize placeholders before writing.
+///
+/// When `normalize` is true, common iOS placeholder tokens like `%@`, `%1$@`, `%ld` are
+/// converted to canonical forms (`%s`, `%1$s`, `%d`) prior to serialization.
+/// Convert with optional placeholder normalization.
+///
+/// Example
+/// ```rust,no_run
+/// use langcodec::formats::FormatType;
+/// use langcodec::converter::convert_with_normalization;
+/// convert_with_normalization(
+///     "en.lproj/Localizable.strings",
+///     FormatType::Strings(Some("en".to_string())),
+///     "values/strings.xml",
+///     FormatType::AndroidStrings(Some("en".to_string())),
+///     true, // normalize placeholders (e.g., %@ -> %s)
+/// )?;
+/// # Ok::<(), langcodec::Error>(())
+/// ```
+pub fn convert_with_normalization<P: AsRef<Path>>(
+    input: P,
+    input_format: FormatType,
+    output: P,
+    output_format: FormatType,
+    normalize: bool,
+) -> Result<(), Error> {
+    let mut input = input.as_ref().to_path_buf();
+    let mut output = output.as_ref().to_path_buf();
+
+    // Carry language between single-language formats
+    let output_format = if let Some(lang) = input_format.language() {
+        output_format.with_language(Some(lang.clone()))
+    } else {
+        output_format
+    };
+
+    if !input_format.matches_language_of(&output_format) {
+        return Err(Error::InvalidResource(
+            "Input and output formats must match in language.".to_string(),
+        ));
+    }
+
+    // Read input as resources
+    let mut resources = match input_format {
+        FormatType::AndroidStrings(_) => vec![AndroidStringsFormat::read_from(&input)?.into()],
+        FormatType::Strings(_) => vec![StringsFormat::read_from(&input)?.into()],
+        FormatType::Xcstrings => Vec::<Resource>::try_from(XcstringsFormat::read_from(&input)?)?,
+        FormatType::CSV => Vec::<Resource>::try_from(CSVFormat::read_from(&input)?)?,
+        FormatType::TSV => Vec::<Resource>::try_from(TSVFormat::read_from(&input)?)?,
+    };
+
+    // Ensure language is set for single-language inputs if provided on input_format
+    if let Some(l) = input_format.language().cloned() {
+        for res in &mut resources {
+            if res.metadata.language.is_empty() {
+                res.metadata.language = l.clone();
+            }
+        }
+    }
+
+    if normalize {
+        for res in &mut resources {
+            for entry in &mut res.entries {
+                match &mut entry.value {
+                    crate::types::Translation::Singular(v) => {
+                        *v = normalize_placeholders(v).into();
+                    }
+                    crate::types::Translation::Plural(p) => {
+                        for (_c, v) in p.forms.iter_mut() {
+                            *v = normalize_placeholders(v);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     // Helper to extract resource by language if present, or first one
     let pick_resource = |lang: Option<String>| -> Option<Resource> {
         match lang {
@@ -223,6 +345,83 @@ pub fn convert_auto<P: AsRef<Path>>(input: P, output: P) -> Result<(), Error> {
     convert(input, input_format, output, output_format)
 }
 
+#[cfg(test)]
+mod normalize_tests {
+    use super::*;
+    use std::fs;
+
+    #[test]
+    fn test_convert_strings_to_android_with_normalization() {
+        let tmp = tempfile::tempdir().unwrap();
+        let strings = tmp.path().join("en.strings");
+        let xml = tmp.path().join("strings.xml");
+
+        fs::write(
+            &strings,
+            "\n\"g\" = \"Hello %@ and %1$@ and %ld\";\n",
+        )
+        .unwrap();
+
+        // Without normalization: convert should succeed
+        convert(
+            &strings,
+            FormatType::Strings(Some("en".into())),
+            &xml,
+            FormatType::AndroidStrings(Some("en".into())),
+        )
+        .unwrap();
+        let content = fs::read_to_string(&xml).unwrap();
+        assert!(content.contains("Hello %"));
+
+        // With normalization
+        convert_with_normalization(
+            &strings,
+            FormatType::Strings(Some("en".into())),
+            &xml,
+            FormatType::AndroidStrings(Some("en".into())),
+            true,
+        )
+        .unwrap();
+        let content = fs::read_to_string(&xml).unwrap();
+        assert!(content.contains("%s"));
+        assert!(content.contains("%1$s"));
+        assert!(content.contains("%d"));
+    }
+}
+
+/// Auto-infer formats from paths and convert, with optional placeholder normalization.
+/// Auto-infer formats and convert with optional placeholder normalization.
+///
+/// Example
+/// ```rust,no_run
+/// use langcodec::converter::convert_auto_with_normalization;
+/// convert_auto_with_normalization(
+///     "Localizable.strings",
+///     "strings.xml",
+///     true, // normalize placeholders
+/// )?;
+/// # Ok::<(), langcodec::Error>(())
+/// ```
+pub fn convert_auto_with_normalization<P: AsRef<Path>>(
+    input: P,
+    output: P,
+    normalize: bool,
+) -> Result<(), Error> {
+    let input_format = infer_format_from_path(&input).ok_or_else(|| {
+        Error::UnknownFormat(format!(
+            "Cannot infer input format from extension: {:?}",
+            input.as_ref().extension()
+        ))
+    })?;
+    let output_format = infer_format_from_path(&output).ok_or_else(|| {
+        Error::UnknownFormat(format!(
+            "Cannot infer output format from extension: {:?}",
+            output.as_ref().extension()
+        ))
+    })?;
+    convert_with_normalization(input, input_format, output, output_format, normalize)
+}
+
 /// Infers a [`FormatType`] from a file path's extension.
 ///
 /// Returns `Some(FormatType)` if the extension matches a known format, otherwise `None`.

langcodec/src/lib.rs

@@ -151,8 +151,9 @@ pub use crate::{
     builder::CodecBuilder,
     codec::Codec,
     converter::{
-        convert, convert_auto, convert_resources_to_format, infer_format_from_extension,
-        infer_format_from_path, infer_language_from_path, merge_resources,
+        convert, convert_auto, convert_resources_to_format, convert_with_normalization,
+        convert_auto_with_normalization, infer_format_from_extension, infer_format_from_path,
+        infer_language_from_path, merge_resources,
     },
     error::Error,
     formats::FormatType,