Skip to main content

langcodec/
codec.rs

1/// This module provides the `Codec` struct and associated functionality for reading,
2/// writing, caching, and loading localized resource files in various formats.
3/// The `Codec` struct manages a collection of `Resource` instances and supports
4/// format inference, language detection from file paths, and serialization.
5///
6/// The module handles different localization file formats such as Apple `.strings`,
7/// Android XML strings, and `.xcstrings`, providing methods to read from files by type
8/// or extension, write resources back to files, and cache resources to JSON.
9///
10use crate::formats::{CSVFormat, TSVFormat};
11use crate::{ConflictStrategy, merge_resources};
12use crate::{
13    error::Error,
14    formats::*,
15    provenance::{ProvenanceRecord, set_resource_provenance},
16    read_options::ReadOptions,
17    traits::Parser,
18    types::{Entry, Resource},
19};
20use std::path::Path;
21
22/// Represents a collection of localized resources and provides methods to read,
23/// write, cache, and load these resources.
24#[derive(Debug, Clone)]
25pub struct Codec {
26    /// The collection of resources managed by this codec.
27    pub resources: Vec<Resource>,
28}
29
30impl Default for Codec {
31    fn default() -> Self {
32        Codec::new()
33    }
34}
35
36impl Codec {
37    /// Creates a new, empty `Codec`.
38    ///
39    /// # Returns
40    ///
41    /// A new `Codec` instance with no resources.
42    pub fn new() -> Self {
43        Codec {
44            resources: Vec::new(),
45        }
46    }
47
48    /// Creates a new `CodecBuilder` for fluent construction.
49    ///
50    /// This method returns a builder that allows you to chain method calls
51    /// to add resources from files and then build the final `Codec` instance.
52    ///
53    /// # Example
54    ///
55    /// ```rust,no_run
56    /// use langcodec::Codec;
57    ///
58    /// let codec = Codec::builder()
59    ///     .add_file("en.strings")?
60    ///     .add_file("fr.strings")?
61    ///     .build();
62    /// # Ok::<(), langcodec::Error>(())
63    /// ```
64    ///
65    /// # Returns
66    ///
67    /// Returns a new `CodecBuilder` instance.
68    pub fn builder() -> crate::builder::CodecBuilder {
69        crate::builder::CodecBuilder::new()
70    }
71
72    /// Returns an iterator over all resources.
73    pub fn iter(&self) -> std::slice::Iter<'_, Resource> {
74        self.resources.iter()
75    }
76
77    /// Returns a mutable iterator over all resources.
78    pub fn iter_mut(&mut self) -> std::slice::IterMut<'_, Resource> {
79        self.resources.iter_mut()
80    }
81
82    /// Finds a resource by its language code, if present.
83    pub fn get_by_language(&self, lang: &str) -> Option<&Resource> {
84        self.resources
85            .iter()
86            .find(|res| res.metadata.language == lang)
87    }
88
89    /// Finds a mutable resource by its language code, if present.
90    pub fn get_mut_by_language(&mut self, lang: &str) -> Option<&mut Resource> {
91        self.resources
92            .iter_mut()
93            .find(|res| res.metadata.language == lang)
94    }
95
96    /// Adds a new resource to the collection.
97    pub fn add_resource(&mut self, resource: Resource) {
98        self.resources.push(resource);
99    }
100
101    /// Appends all resources from another `Codec` into this one.
102    pub fn extend_from(&mut self, mut other: Codec) {
103        self.resources.append(&mut other.resources);
104    }
105
106    /// Constructs a `Codec` from multiple `Codec` instances by concatenating their resources.
107    pub fn from_codecs<I>(codecs: I) -> Self
108    where
109        I: IntoIterator<Item = Codec>,
110    {
111        let mut combined = Codec::new();
112        for mut c in codecs {
113            combined.resources.append(&mut c.resources);
114        }
115        combined
116    }
117
118    /// Merges multiple `Codec` instances into one and merges resources by language using the given strategy.
119    ///
120    /// Returns the merged `Codec` containing resources merged per language group.
121    pub fn merge_codecs<I>(codecs: I, strategy: &ConflictStrategy) -> Self
122    where
123        I: IntoIterator<Item = Codec>,
124    {
125        let mut combined = Codec::from_codecs(codecs);
126        let _ = combined.merge_resources(strategy);
127        combined
128    }
129
130    // ===== HIGH-LEVEL MODIFICATION METHODS =====
131
132    /// Finds an entry by its key across all languages.
133    ///
134    /// Returns an iterator over all resources and their matching entries.
135    ///
136    /// # Arguments
137    ///
138    /// * `key` - The entry key to search for
139    ///
140    /// # Returns
141    ///
142    /// An iterator yielding `(&Resource, &Entry)` pairs for all matching entries.
143    ///
144    /// # Example
145    ///
146    /// ```rust
147    /// use langcodec::Codec;
148    ///
149    /// let mut codec = Codec::new();
150    /// // ... load resources ...
151    ///
152    /// for (resource, entry) in codec.find_entries("welcome_message") {
153    ///     println!("{}: {}", resource.metadata.language, entry.value);
154    /// }
155    /// ```
156    pub fn find_entries(&self, key: &str) -> Vec<(&Resource, &Entry)> {
157        let mut results = Vec::new();
158        for resource in &self.resources {
159            if let Some(entry) = resource.find_entry(key) {
160                results.push((resource, entry));
161            }
162        }
163        results
164    }
165
166    /// Finds an entry by its key in a specific language.
167    ///
168    /// # Arguments
169    ///
170    /// * `key` - The entry key to search for
171    /// * `language` - The language code (e.g., "en", "fr")
172    ///
173    /// # Returns
174    ///
175    /// `Some(&Entry)` if found, `None` otherwise.
176    ///
177    /// # Example
178    ///
179    /// ```rust
180    /// use langcodec::Codec;
181    ///
182    /// let mut codec = Codec::new();
183    /// // ... load resources ...
184    ///
185    /// if let Some(entry) = codec.find_entry("welcome_message", "en") {
186    ///     println!("English welcome: {}", entry.value);
187    /// }
188    /// ```
189    pub fn find_entry(&self, key: &str, language: &str) -> Option<&Entry> {
190        self.get_by_language(language)?.find_entry(key)
191    }
192
193    /// Finds a mutable entry by its key in a specific language.
194    ///
195    /// # Arguments
196    ///
197    /// * `key` - The entry key to search for
198    /// * `language` - The language code (e.g., "en", "fr")
199    ///
200    /// # Returns
201    ///
202    /// `Some(&mut Entry)` if found, `None` otherwise.
203    ///
204    /// # Example
205    ///
206    /// ```rust
207    /// use langcodec::Codec;
208    /// use langcodec::types::Translation;
209    ///
210    /// let mut codec = Codec::new();
211    /// // ... load resources ...
212    ///
213    /// if let Some(entry) = codec.find_entry_mut("welcome_message", "en") {
214    ///     entry.value = Translation::Singular("Hello, World!".to_string());
215    ///     entry.status = langcodec::types::EntryStatus::Translated;
216    /// }
217    /// ```
218    pub fn find_entry_mut(&mut self, key: &str, language: &str) -> Option<&mut Entry> {
219        self.get_mut_by_language(language)?.find_entry_mut(key)
220    }
221
222    /// Updates a translation for a specific key and language.
223    ///
224    /// # Arguments
225    ///
226    /// * `key` - The entry key to update
227    /// * `language` - The language code (e.g., "en", "fr")
228    /// * `translation` - The new translation value
229    /// * `status` - Optional new status (defaults to `Translated`)
230    ///
231    /// # Returns
232    ///
233    /// `Ok(())` if the entry was found and updated, `Err` if not found.
234    ///
235    /// # Example
236    ///
237    /// ```rust
238    /// use langcodec::{Codec, types::{Translation, EntryStatus}};
239    ///
240    /// let mut codec = Codec::new();
241    /// // Add an entry first
242    /// codec.add_entry("welcome", "en", Translation::Singular("Hello".to_string()), None, None)?;
243    ///
244    /// codec.update_translation(
245    ///     "welcome",
246    ///     "en",
247    ///     Translation::Singular("Hello, World!".to_string()),
248    ///     Some(EntryStatus::Translated)
249    /// )?;
250    /// # Ok::<(), langcodec::Error>(())
251    /// ```
252    pub fn update_translation(
253        &mut self,
254        key: &str,
255        language: &str,
256        translation: crate::types::Translation,
257        status: Option<crate::types::EntryStatus>,
258    ) -> Result<(), Error> {
259        if let Some(entry) = self.find_entry_mut(key, language) {
260            entry.value = translation;
261            if let Some(new_status) = status {
262                entry.status = new_status;
263            }
264            Ok(())
265        } else {
266            Err(Error::InvalidResource(format!(
267                "Entry '{}' not found in language '{}'",
268                key, language
269            )))
270        }
271    }
272
273    /// Adds a new entry to a specific language.
274    ///
275    /// If the language doesn't exist, it will be created automatically.
276    ///
277    /// # Arguments
278    ///
279    /// * `key` - The entry key
280    /// * `language` - The language code (e.g., "en", "fr")
281    /// * `translation` - The translation value
282    /// * `comment` - Optional comment for translators
283    /// * `status` - Optional status (defaults to `New`)
284    ///
285    /// # Returns
286    ///
287    /// `Ok(())` if the entry was added successfully.
288    ///
289    /// # Example
290    ///
291    /// ```rust
292    /// use langcodec::{Codec, types::{Translation, EntryStatus}};
293    ///
294    /// let mut codec = Codec::new();
295    ///
296    /// codec.add_entry(
297    ///     "new_message",
298    ///     "en",
299    ///     Translation::Singular("This is a new message".to_string()),
300    ///     Some("This is a new message for users".to_string()),
301    ///     Some(EntryStatus::New)
302    /// )?;
303    /// # Ok::<(), langcodec::Error>(())
304    /// ```
305    pub fn add_entry(
306        &mut self,
307        key: &str,
308        language: &str,
309        translation: crate::types::Translation,
310        comment: Option<String>,
311        status: Option<crate::types::EntryStatus>,
312    ) -> Result<(), Error> {
313        // Find or create the resource for this language
314        let resource = if let Some(resource) = self.get_mut_by_language(language) {
315            resource
316        } else {
317            // Create a new resource for this language
318            let new_resource = crate::types::Resource {
319                metadata: crate::types::Metadata {
320                    language: language.to_string(),
321                    domain: "".to_string(),
322                    custom: std::collections::HashMap::new(),
323                },
324                entries: Vec::new(),
325            };
326            self.add_resource(new_resource);
327            self.get_mut_by_language(language).unwrap()
328        };
329
330        let entry = crate::types::Entry {
331            id: key.to_string(),
332            value: translation,
333            comment,
334            status: status.unwrap_or(crate::types::EntryStatus::New),
335            custom: std::collections::HashMap::new(),
336        };
337        resource.add_entry(entry);
338        Ok(())
339    }
340
341    /// Removes an entry from a specific language.
342    ///
343    /// # Arguments
344    ///
345    /// * `key` - The entry key to remove
346    /// * `language` - The language code (e.g., "en", "fr")
347    ///
348    /// # Returns
349    ///
350    /// `Ok(())` if the entry was found and removed, `Err` if not found.
351    ///
352    /// # Example
353    ///
354    /// ```rust
355    /// use langcodec::{Codec, types::{Translation, EntryStatus}};
356    ///
357    /// let mut codec = Codec::new();
358    /// // Add a resource first
359    /// codec.add_entry("test_key", "en", Translation::Singular("Test".to_string()), None, None)?;
360    ///
361    /// // Now remove it
362    /// codec.remove_entry("test_key", "en")?;
363    /// # Ok::<(), langcodec::Error>(())
364    /// ```
365    pub fn remove_entry(&mut self, key: &str, language: &str) -> Result<(), Error> {
366        if let Some(resource) = self.get_mut_by_language(language) {
367            let initial_len = resource.entries.len();
368            resource.entries.retain(|entry| entry.id != key);
369
370            if resource.entries.len() == initial_len {
371                Err(Error::InvalidResource(format!(
372                    "Entry '{}' not found in language '{}'",
373                    key, language
374                )))
375            } else {
376                Ok(())
377            }
378        } else {
379            Err(Error::InvalidResource(format!(
380                "Language '{}' not found",
381                language
382            )))
383        }
384    }
385
386    /// Copies an entry from one language to another.
387    ///
388    /// This is useful for creating new translations based on existing ones.
389    ///
390    /// # Arguments
391    ///
392    /// * `key` - The entry key to copy
393    /// * `from_language` - The source language
394    /// * `to_language` - The target language
395    /// * `update_status` - Whether to update the status to `New` in the target language
396    ///
397    /// # Returns
398    ///
399    /// `Ok(())` if the entry was copied successfully, `Err` if not found.
400    ///
401    /// # Example
402    ///
403    /// ```rust
404    /// use langcodec::{Codec, types::{Translation, EntryStatus}};
405    ///
406    /// let mut codec = Codec::new();
407    /// // Add source entry first
408    /// codec.add_entry("welcome", "en", Translation::Singular("Hello".to_string()), None, None)?;
409    ///
410    /// // Copy English entry to French as a starting point
411    /// codec.copy_entry("welcome", "en", "fr", true)?;
412    /// # Ok::<(), langcodec::Error>(())
413    /// ```
414    pub fn copy_entry(
415        &mut self,
416        key: &str,
417        from_language: &str,
418        to_language: &str,
419        update_status: bool,
420    ) -> Result<(), Error> {
421        let source_entry = self.find_entry(key, from_language).ok_or_else(|| {
422            Error::InvalidResource(format!(
423                "Entry '{}' not found in source language '{}'",
424                key, from_language
425            ))
426        })?;
427
428        let mut new_entry = source_entry.clone();
429        if update_status {
430            new_entry.status = crate::types::EntryStatus::New;
431        }
432
433        // Find or create the target resource
434        let target_resource = if let Some(resource) = self.get_mut_by_language(to_language) {
435            resource
436        } else {
437            // Create a new resource for the target language
438            let new_resource = crate::types::Resource {
439                metadata: crate::types::Metadata {
440                    language: to_language.to_string(),
441                    domain: "".to_string(),
442                    custom: std::collections::HashMap::new(),
443                },
444                entries: Vec::new(),
445            };
446            self.add_resource(new_resource);
447            self.get_mut_by_language(to_language).unwrap()
448        };
449
450        // Remove existing entry if it exists
451        target_resource.entries.retain(|entry| entry.id != key);
452        target_resource.add_entry(new_entry);
453        Ok(())
454    }
455
456    /// Gets all languages available in the codec.
457    ///
458    /// # Returns
459    ///
460    /// An iterator over all language codes.
461    ///
462    /// # Example
463    ///
464    /// ```rust
465    /// use langcodec::Codec;
466    ///
467    /// let codec = Codec::new();
468    /// // ... load resources ...
469    ///
470    /// for language in codec.languages() {
471    ///     println!("Available language: {}", language);
472    /// }
473    /// ```
474    pub fn languages(&self) -> impl Iterator<Item = &str> {
475        self.resources.iter().map(|r| r.metadata.language.as_str())
476    }
477
478    /// Gets all unique entry keys across all languages.
479    ///
480    /// # Returns
481    ///
482    /// An iterator over all unique entry keys.
483    ///
484    /// # Example
485    ///
486    /// ```rust
487    /// use langcodec::Codec;
488    ///
489    /// let codec = Codec::new();
490    /// // ... load resources ...
491    ///
492    /// for key in codec.all_keys() {
493    ///     println!("Available key: {}", key);
494    /// }
495    /// ```
496    pub fn all_keys(&self) -> impl Iterator<Item = &str> {
497        use std::collections::HashSet;
498
499        let mut keys = HashSet::new();
500        for resource in &self.resources {
501            for entry in &resource.entries {
502                keys.insert(entry.id.as_str());
503            }
504        }
505        keys.into_iter()
506    }
507
508    /// Checks if an entry exists in a specific language.
509    ///
510    /// # Arguments
511    ///
512    /// * `key` - The entry key to check
513    /// * `language` - The language code (e.g., "en", "fr")
514    ///
515    /// # Returns
516    ///
517    /// `true` if the entry exists, `false` otherwise.
518    ///
519    /// # Example
520    ///
521    /// ```rust
522    /// use langcodec::Codec;
523    ///
524    /// let codec = Codec::new();
525    /// // ... load resources ...
526    ///
527    /// if codec.has_entry("welcome_message", "en") {
528    ///     println!("English welcome message exists");
529    /// }
530    /// ```
531    pub fn has_entry(&self, key: &str, language: &str) -> bool {
532        self.find_entry(key, language).is_some()
533    }
534
535    /// Gets the count of entries in a specific language.
536    ///
537    /// # Arguments
538    ///
539    /// * `language` - The language code (e.g., "en", "fr")
540    ///
541    /// # Returns
542    ///
543    /// The number of entries in the specified language, or 0 if the language doesn't exist.
544    ///
545    /// # Example
546    ///
547    /// ```rust
548    /// use langcodec::Codec;
549    ///
550    /// let codec = Codec::new();
551    /// // ... load resources ...
552    ///
553    /// let count = codec.entry_count("en");
554    /// println!("English has {} entries", count);
555    /// ```
556    pub fn entry_count(&self, language: &str) -> usize {
557        self.get_by_language(language)
558            .map(|r| r.entries.len())
559            .unwrap_or(0)
560    }
561
562    /// Validates the codec for common issues.
563    ///
564    /// # Returns
565    ///
566    /// `Ok(())` if validation passes, `Err(Error)` with details if validation fails.
567    ///
568    /// # Example
569    ///
570    /// ```rust
571    /// use langcodec::Codec;
572    ///
573    /// let mut codec = Codec::new();
574    /// // ... add resources ...
575    ///
576    /// if let Err(validation_error) = codec.validate() {
577    ///     eprintln!("Validation failed: {}", validation_error);
578    /// }
579    /// ```
580    pub fn validate(&self) -> Result<(), Error> {
581        // Check for empty resources
582        if self.resources.is_empty() {
583            return Err(Error::InvalidResource("No resources found".to_string()));
584        }
585
586        // Check for duplicate languages
587        let mut languages = std::collections::HashSet::new();
588        for resource in &self.resources {
589            if !languages.insert(&resource.metadata.language) {
590                return Err(Error::InvalidResource(format!(
591                    "Duplicate language found: {}",
592                    resource.metadata.language
593                )));
594            }
595        }
596
597        // Check for empty resources
598        for resource in &self.resources {
599            if resource.entries.is_empty() {
600                return Err(Error::InvalidResource(format!(
601                    "Resource for language '{}' has no entries",
602                    resource.metadata.language
603                )));
604            }
605        }
606
607        Ok(())
608    }
609
610    /// Validates plural completeness per CLDR category sets for each locale.
611    ///
612    /// For each plural entry in each resource, checks that all required plural
613    /// categories for the language are present. Returns a Validation error with
614    /// aggregated details if any are missing.
615    pub fn validate_plurals(&self) -> Result<(), Error> {
616        use crate::plural_rules::collect_resource_plural_issues;
617
618        let mut reports = Vec::new();
619        for res in &self.resources {
620            reports.extend(collect_resource_plural_issues(res));
621        }
622
623        if reports.is_empty() {
624            return Ok(());
625        }
626
627        // Fold into an Error message for the validating API
628        let mut lines = Vec::new();
629        for r in reports {
630            let miss: Vec<String> = r.missing.iter().map(|k| format!("{:?}", k)).collect();
631            let have: Vec<String> = r.have.iter().map(|k| format!("{:?}", k)).collect();
632            lines.push(format!(
633                "lang='{}' key='{}': missing plural categories: [{}] (have: [{}])",
634                r.language,
635                r.key,
636                miss.join(", "),
637                have.join(", ")
638            ));
639        }
640        Err(Error::validation_error(lines.join("\n")))
641    }
642
643    /// Collects non-fatal plural validation reports across all resources.
644    pub fn collect_plural_issues(&self) -> Vec<crate::plural_rules::PluralValidationReport> {
645        use crate::plural_rules::collect_resource_plural_issues;
646        let mut reports = Vec::new();
647        for res in &self.resources {
648            reports.extend(collect_resource_plural_issues(res));
649        }
650        reports
651    }
652
653    /// Autofix: fill missing plural categories using 'other' and mark entries as NeedsReview.
654    /// Returns total categories added across all resources.
655    pub fn autofix_fill_missing_from_other(&mut self) -> usize {
656        use crate::plural_rules::autofix_fill_missing_from_other_resource;
657        let mut total = 0usize;
658        for res in &mut self.resources {
659            total += autofix_fill_missing_from_other_resource(res);
660        }
661        total
662    }
663
664    /// Cleans up resources by removing empty resources and entries.
665    pub fn clean_up_resources(&mut self) {
666        self.resources
667            .retain(|resource| !resource.entries.is_empty());
668    }
669
670    /// Validate placeholder consistency across languages for each key.
671    ///
672    /// Rules (initial version):
673    /// - For each key, each language must have the same placeholder signature.
674    /// - For plural entries, all forms within a language must share the same signature.
675    /// - iOS vs Android differences like `%@`/`%1$@` vs `%s`/`%1$s` are normalized.
676    ///
677    /// Example
678    /// ```rust
679    /// use langcodec::{Codec, types::{Entry, EntryStatus, Metadata, Resource, Translation}};
680    /// let mut codec = Codec::new();
681    /// let en = Resource{
682    ///     metadata: Metadata{ language: "en".into(), domain: String::new(), custom: Default::default() },
683    ///     entries: vec![Entry{ id: "greet".into(), value: Translation::Singular("Hello %1$@".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
684    /// };
685    /// let fr = Resource{
686    ///     metadata: Metadata{ language: "fr".into(), domain: String::new(), custom: Default::default() },
687    ///     entries: vec![Entry{ id: "greet".into(), value: Translation::Singular("Bonjour %1$s".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
688    /// };
689    /// codec.add_resource(en);
690    /// codec.add_resource(fr);
691    /// assert!(codec.validate_placeholders(true).is_ok());
692    /// ```
693    pub fn validate_placeholders(&self, strict: bool) -> Result<(), Error> {
694        use crate::placeholder::signature;
695        use crate::types::Translation;
696        use std::collections::HashMap;
697
698        // key -> lang -> Vec<signatures per form or single>
699        let mut map: HashMap<String, HashMap<String, Vec<Vec<String>>>> = HashMap::new();
700
701        for res in &self.resources {
702            for entry in &res.entries {
703                let sigs: Vec<Vec<String>> = match &entry.value {
704                    Translation::Empty => vec![],
705                    Translation::Singular(v) => vec![signature(v)],
706                    Translation::Plural(p) => p.forms.values().map(|v| signature(v)).collect(),
707                };
708                map.entry(entry.id.clone())
709                    .or_default()
710                    .entry(res.metadata.language.clone())
711                    .or_default()
712                    .push(sigs.into_iter().flatten().collect());
713            }
714        }
715
716        let mut problems = Vec::new();
717
718        for (key, langs) in map {
719            // Per-language: ensure all collected signatures for this entry are identical
720            let mut per_lang_sig: HashMap<String, Vec<String>> = HashMap::new();
721            for (lang, sig_lists) in langs {
722                if let Some(first) = sig_lists.first() {
723                    if sig_lists.iter().any(|s| s != first) {
724                        problems.push(format!(
725                            "Key '{}' in '{}': inconsistent placeholders across forms: {:?}",
726                            key, lang, sig_lists
727                        ));
728                    }
729                    per_lang_sig.insert(lang, first.clone());
730                }
731            }
732
733            // Across languages, pick one baseline and compare
734            if let Some((base_lang, base_sig)) = per_lang_sig.iter().next() {
735                for (lang, sig) in &per_lang_sig {
736                    if sig != base_sig {
737                        problems.push(format!(
738                            "Key '{}' mismatch: {} {:?} vs {} {:?}",
739                            key, base_lang, base_sig, lang, sig
740                        ));
741                    }
742                }
743            }
744        }
745
746        if problems.is_empty() {
747            return Ok(());
748        }
749        if strict {
750            return Err(Error::validation_error(format!(
751                "Placeholder issues: {}",
752                problems.join(" | ")
753            )));
754        }
755        // Non-strict mode: treat as success
756        Ok(())
757    }
758
759    /// Collect placeholder issues without failing.
760    /// Returns a list of human-readable messages; empty if none.
761    ///
762    /// Useful to warn in non-strict mode.
763    pub fn collect_placeholder_issues(&self) -> Vec<String> {
764        use crate::placeholder::signature;
765        use crate::types::Translation;
766        use std::collections::HashMap;
767
768        let mut map: HashMap<String, HashMap<String, Vec<Vec<String>>>> = HashMap::new();
769        for res in &self.resources {
770            for entry in &res.entries {
771                let sigs: Vec<Vec<String>> = match &entry.value {
772                    Translation::Empty => vec![],
773                    Translation::Singular(v) => vec![signature(v)],
774                    Translation::Plural(p) => p.forms.values().map(|v| signature(v)).collect(),
775                };
776                map.entry(entry.id.clone())
777                    .or_default()
778                    .entry(res.metadata.language.clone())
779                    .or_default()
780                    .push(sigs.into_iter().flatten().collect());
781            }
782        }
783
784        let mut problems = Vec::new();
785        for (key, langs) in map {
786            let mut per_lang_sig: HashMap<String, Vec<String>> = HashMap::new();
787            for (lang, sig_lists) in langs {
788                if let Some(first) = sig_lists.first() {
789                    if sig_lists.iter().any(|s| s != first) {
790                        problems.push(format!(
791                            "Key '{}' in '{}': inconsistent placeholders across forms: {:?}",
792                            key, lang, sig_lists
793                        ));
794                    }
795                    per_lang_sig.insert(lang, first.clone());
796                }
797            }
798            if let Some((base_lang, base_sig)) = per_lang_sig.iter().next() {
799                for (lang, sig) in &per_lang_sig {
800                    if sig != base_sig {
801                        problems.push(format!(
802                            "Key '{}' mismatch: {} {:?} vs {} {:?}",
803                            key, base_lang, base_sig, lang, sig
804                        ));
805                    }
806                }
807            }
808        }
809        problems
810    }
811
812    /// Normalize placeholders in ordinary entries (mutates in place).
813    /// Converts iOS patterns like `%@`, `%1$@`, `%ld` to canonical forms (%s, %1$s, %d/%u).
814    ///
815    /// Entries carrying any Apple `.stringsdict` structural custom key are
816    /// skipped, including entries with only partial structural metadata.
817    /// Rewriting those printf tokens could make the retained selector value
818    /// type inconsistent with the translation. Use the fallible
819    /// [`crate::normalize_codec`] API when callers need an explicit error for
820    /// this condition.
821    ///
822    /// Example
823    /// ```rust
824    /// use langcodec::{Codec, types::{Entry, EntryStatus, Metadata, Resource, Translation}};
825    /// let mut codec = Codec::new();
826    /// codec.add_resource(Resource{
827    ///     metadata: Metadata{ language: "en".into(), domain: String::new(), custom: Default::default() },
828    ///     entries: vec![Entry{ id: "id".into(), value: Translation::Singular("Hello %@ and %1$@".into()), comment: None, status: EntryStatus::Translated, custom: Default::default() }]
829    /// });
830    /// codec.normalize_placeholders_in_place();
831    /// let v = match &codec.resources[0].entries[0].value { Translation::Singular(v) => v.clone(), _ => unreachable!() };
832    /// assert!(v.contains("%s") && v.contains("%1$s"));
833    /// ```
834    pub fn normalize_placeholders_in_place(&mut self) {
835        use crate::placeholder::normalize_placeholders;
836        use crate::types::Translation;
837        for res in &mut self.resources {
838            for entry in &mut res.entries {
839                if crate::normalize::has_stringsdict_structural_metadata(entry) {
840                    continue;
841                }
842
843                match &mut entry.value {
844                    Translation::Empty => {
845                        continue;
846                    }
847                    Translation::Singular(v) => {
848                        let nv = normalize_placeholders(v);
849                        *v = nv;
850                    }
851                    Translation::Plural(p) => {
852                        for v in p.forms.values_mut() {
853                            let nv = normalize_placeholders(v);
854                            *v = nv;
855                        }
856                    }
857                }
858            }
859        }
860    }
861
862    /// Merge resources with the same language by the given strategy.
863    ///
864    /// This method groups resources by language and merges multiple resources
865    /// that share the same language into a single resource. Resources with
866    /// unique languages are left unchanged.
867    ///
868    /// # Arguments
869    ///
870    /// * `strategy` - The conflict resolution strategy to use when merging
871    ///   entries with the same ID across multiple resources
872    ///
873    /// # Returns
874    ///
875    /// The number of merge operations performed. A merge operation occurs
876    /// when there are 2 or more resources for the same language.
877    ///
878    /// # Example
879    ///
880    /// ```rust
881    /// use langcodec::{Codec, types::ConflictStrategy};
882    ///
883    /// let mut codec = Codec::new();
884    /// // ... add resources with same language ...
885    ///
886    /// let merges_performed = codec.merge_resources(&ConflictStrategy::Last);
887    /// println!("Merged {} language groups", merges_performed);
888    /// ```
889    ///
890    /// # Behavior
891    ///
892    /// - Resources are grouped by language
893    /// - Only languages with multiple resources are merged
894    /// - The merged resource replaces all original resources for that language
895    /// - Resources with unique languages remain unchanged
896    /// - Entries are merged according to the specified conflict strategy
897    pub fn merge_resources(&mut self, strategy: &ConflictStrategy) -> usize {
898        // Group resources by language
899        let mut grouped_resources: std::collections::HashMap<String, Vec<Resource>> =
900            std::collections::HashMap::new();
901        for resource in &self.resources {
902            grouped_resources
903                .entry(resource.metadata.language.clone())
904                .or_default()
905                .push(resource.clone());
906        }
907
908        let mut merge_count = 0;
909
910        // Merge resources by language
911        for (_language, resources) in grouped_resources {
912            if resources.len() > 1 {
913                match merge_resources(&resources, strategy) {
914                    Ok(merged) => {
915                        // Replace the original resources with the merged resource and remove the original resources
916                        self.resources.retain(|r| r.metadata.language != _language);
917                        self.resources.push(merged);
918                        merge_count += 1;
919                    }
920                    Err(e) => {
921                        // Based on the current implementation, the merge_resources should never return an error
922                        // because we are merging resources with the same language
923                        // so we should panic here
924                        panic!("Unexpected error merging resources: {}", e);
925                    }
926                }
927            }
928        }
929
930        merge_count
931    }
932
933    /// Writes a resource to a file with automatic format detection.
934    ///
935    /// # Arguments
936    ///
937    /// * `resource` - The resource to write
938    /// * `output_path` - The output file path
939    ///
940    /// # Returns
941    ///
942    /// `Ok(())` on success, `Err(Error)` on failure.
943    ///
944    /// # Example
945    ///
946    /// ```rust,no_run
947    /// use langcodec::{Codec, types::{Resource, Metadata, Entry, Translation, EntryStatus}};
948    ///
949    /// let resource = Resource {
950    ///     metadata: Metadata {
951    ///         language: "en".to_string(),
952    ///         domain: "domain".to_string(),
953    ///         custom: std::collections::HashMap::new(),
954    ///     },
955    ///     entries: vec![],
956    /// };
957    /// Codec::write_resource_to_file(&resource, "output.strings")?;
958    /// # Ok::<(), langcodec::Error>(())
959    /// ```
960    pub fn write_resource_to_file(resource: &Resource, output_path: &str) -> Result<(), Error> {
961        use crate::formats::{
962            AndroidStringsFormat, CSVFormat, StringsFormat, StringsdictFormat, TSVFormat,
963            XcstringsFormat,
964        };
965        use std::path::Path;
966
967        // Infer format from output path
968        let format_type =
969            crate::converter::infer_format_from_extension(output_path).ok_or_else(|| {
970                Error::InvalidResource(format!(
971                    "Cannot infer format from output path: {}",
972                    output_path
973                ))
974            })?;
975
976        match format_type {
977            crate::formats::FormatType::AndroidStrings(_) => {
978                AndroidStringsFormat::from(resource.clone()).write_to(Path::new(output_path))
979            }
980            crate::formats::FormatType::Strings(_) => StringsFormat::try_from(resource.clone())
981                .and_then(|format| format.write_to(Path::new(output_path))),
982            crate::formats::FormatType::Stringsdict(_) => {
983                StringsdictFormat::try_from(resource.clone())
984                    .and_then(|format| format.write_to(Path::new(output_path)))
985            }
986            crate::formats::FormatType::Xcstrings => {
987                XcstringsFormat::try_from(vec![resource.clone()])
988                    .and_then(|format| format.write_to(Path::new(output_path)))
989            }
990            crate::formats::FormatType::Xliff(_) => Err(Error::InvalidResource(
991                "XLIFF output requires both source and target resources; use convert_resources_to_format instead of write_resource_to_file".to_string(),
992            )),
993            crate::formats::FormatType::CSV => CSVFormat::try_from(vec![resource.clone()])
994                .and_then(|format| format.write_to(Path::new(output_path))),
995            crate::formats::FormatType::TSV => TSVFormat::try_from(vec![resource.clone()])
996                .and_then(|format| format.write_to(Path::new(output_path))),
997        }
998    }
999
1000    /// Reads a resource file given its path and explicit format type.
1001    ///
1002    /// # Parameters
1003    /// - `path`: Path to the resource file.
1004    /// - `format_type`: The format type of the resource file.
1005    ///
1006    /// # Returns
1007    ///
1008    /// `Ok(())` if the file was successfully read and resources loaded,
1009    /// or an `Error` otherwise.
1010    pub fn read_file_by_type<P: AsRef<Path>>(
1011        &mut self,
1012        path: P,
1013        format_type: FormatType,
1014    ) -> Result<(), Error> {
1015        self.read_file_by_type_with_options(path, format_type, &ReadOptions::default())
1016    }
1017
1018    /// Reads a resource file given its path and explicit format type with read options.
1019    pub fn read_file_by_type_with_options<P: AsRef<Path>>(
1020        &mut self,
1021        path: P,
1022        format_type: FormatType,
1023        options: &ReadOptions,
1024    ) -> Result<(), Error> {
1025        let inferred_language = crate::converter::infer_language_from_path(&path, &format_type)?;
1026        let format_language = match &format_type {
1027            FormatType::Strings(lang_opt)
1028            | FormatType::Stringsdict(lang_opt)
1029            | FormatType::AndroidStrings(lang_opt) => lang_opt.clone(),
1030            FormatType::Xliff(lang_opt) => lang_opt.clone(),
1031            _ => None,
1032        };
1033
1034        let language = options
1035            .language_hint
1036            .clone()
1037            .or(format_language)
1038            .or(inferred_language);
1039        let requires_language = matches!(
1040            &format_type,
1041            FormatType::Strings(_) | FormatType::Stringsdict(_) | FormatType::AndroidStrings(_)
1042        );
1043        let format_name = format_type.to_string();
1044        let source_path = path.as_ref().to_string_lossy().to_string();
1045
1046        if options.strict && requires_language && language.is_none() {
1047            return Err(Error::missing_language(
1048                source_path.clone(),
1049                format_name.clone(),
1050            ));
1051        }
1052
1053        let domain = path
1054            .as_ref()
1055            .file_stem()
1056            .and_then(|s| s.to_str())
1057            .unwrap_or_default()
1058            .to_string();
1059        let path = path.as_ref();
1060
1061        let mut preserve_parsed_metadata = false;
1062        let mut new_resources = match &format_type {
1063            FormatType::Strings(_) => {
1064                vec![Resource::from(StringsFormat::read_from(path)?)]
1065            }
1066            FormatType::Stringsdict(_) => {
1067                vec![Resource::from(StringsdictFormat::read_from(path)?)]
1068            }
1069            FormatType::AndroidStrings(_) => {
1070                vec![Resource::from(AndroidStringsFormat::read_from(path)?)]
1071            }
1072            FormatType::Xcstrings => Vec::<Resource>::try_from(XcstringsFormat::read_from(path)?)?,
1073            FormatType::Xliff(_) => Vec::<Resource>::try_from(XliffFormat::read_from(path)?)?,
1074            FormatType::CSV => {
1075                // Parse CSV format and convert to resources
1076                let csv_format = CSVFormat::read_from(path)?;
1077                preserve_parsed_metadata = csv_format.is_extended();
1078                Vec::<Resource>::try_from(csv_format)?
1079            }
1080            FormatType::TSV => {
1081                // Parse TSV format and convert to resources
1082                let tsv_format = TSVFormat::read_from(path)?;
1083                preserve_parsed_metadata = tsv_format.is_extended();
1084                Vec::<Resource>::try_from(tsv_format)?
1085            }
1086        };
1087
1088        for new_resource in &mut new_resources {
1089            if requires_language && let Some(ref lang) = language {
1090                new_resource.metadata.language = lang.clone();
1091            }
1092            if !preserve_parsed_metadata {
1093                new_resource.metadata.domain = domain.clone();
1094                new_resource
1095                    .metadata
1096                    .custom
1097                    .insert("format".to_string(), format_name.clone());
1098            }
1099
1100            if options.attach_provenance {
1101                set_resource_provenance(
1102                    new_resource,
1103                    &ProvenanceRecord {
1104                        source_path: Some(source_path.clone()),
1105                        source_format: Some(format_name.clone()),
1106                        source_language: language.clone(),
1107                        ..ProvenanceRecord::default()
1108                    },
1109                );
1110            }
1111        }
1112        self.resources.append(&mut new_resources);
1113
1114        Ok(())
1115    }
1116
1117    /// Reads a resource file by inferring its format from the file extension.
1118    /// Optionally infers language from the path if not provided.
1119    ///
1120    /// # Parameters
1121    /// - `path`: Path to the resource file.
1122    /// - `lang`: Optional language code to use.
1123    ///
1124    /// # Returns
1125    ///
1126    /// `Ok(())` if the file was successfully read,
1127    /// or an `Error` if the format is unsupported or reading fails.
1128    pub fn read_file_by_extension<P: AsRef<Path>>(
1129        &mut self,
1130        path: P,
1131        lang: Option<String>,
1132    ) -> Result<(), Error> {
1133        self.read_file_by_extension_with_options(path, &ReadOptions::new().with_language_hint(lang))
1134    }
1135
1136    /// Reads a resource file by inferring format from extension with read options.
1137    pub fn read_file_by_extension_with_options<P: AsRef<Path>>(
1138        &mut self,
1139        path: P,
1140        options: &ReadOptions,
1141    ) -> Result<(), Error> {
1142        let format_type = match path.as_ref().extension().and_then(|s| s.to_str()) {
1143            Some("xml") => FormatType::AndroidStrings(options.language_hint.clone()),
1144            Some("strings") => FormatType::Strings(options.language_hint.clone()),
1145            Some("stringsdict") => FormatType::Stringsdict(options.language_hint.clone()),
1146            Some("xcstrings") => FormatType::Xcstrings,
1147            Some("xliff") => FormatType::Xliff(None),
1148            Some("csv") => FormatType::CSV,
1149            Some("tsv") => FormatType::TSV,
1150            extension => {
1151                return Err(Error::UnsupportedFormat(format!(
1152                    "Unsupported file extension: {:?}.",
1153                    extension
1154                )));
1155            }
1156        };
1157
1158        self.read_file_by_type_with_options(path, format_type, options)?;
1159
1160        Ok(())
1161    }
1162
1163    /// Writes all managed resources back to their respective files,
1164    /// grouped by domain.
1165    ///
1166    /// # Returns
1167    ///
1168    /// `Ok(())` if all writes succeed, or an `Error` otherwise.
1169    pub fn write_to_file(&self) -> Result<(), Error> {
1170        // Group resources by the domain in a HashMap
1171        let mut grouped_resources: std::collections::HashMap<String, Vec<Resource>> =
1172            std::collections::HashMap::new();
1173        for resource in &*self.resources {
1174            let domain = resource.metadata.domain.clone();
1175            grouped_resources
1176                .entry(domain)
1177                .or_default()
1178                .push(resource.clone());
1179        }
1180
1181        // Iterate the map and write each resource to its respective file
1182        for (domain, resources) in grouped_resources {
1183            crate::converter::write_resources_to_file(&resources, &domain)?;
1184        }
1185
1186        Ok(())
1187    }
1188
1189    /// Caches the current resources to a JSON file.
1190    ///
1191    /// # Parameters
1192    /// - `path`: Destination file path for the cache.
1193    ///
1194    /// # Returns
1195    ///
1196    /// `Ok(())` if caching succeeds, or an `Error` if file I/O or serialization fails.
1197    pub fn cache_to_file<P: AsRef<Path>>(&self, path: P) -> Result<(), Error> {
1198        let path = path.as_ref();
1199        if let Some(parent) = path.parent() {
1200            std::fs::create_dir_all(parent).map_err(Error::Io)?;
1201        }
1202        let mut writer = std::fs::File::create(path).map_err(Error::Io)?;
1203        serde_json::to_writer(&mut writer, &*self.resources).map_err(Error::Parse)?;
1204        Ok(())
1205    }
1206
1207    /// Loads resources from a JSON cache file.
1208    ///
1209    /// # Parameters
1210    /// - `path`: Path to the JSON file containing cached resources.
1211    ///
1212    /// # Returns
1213    ///
1214    /// `Ok(Codec)` with loaded resources, or an `Error` if loading or deserialization fails.
1215    pub fn load_from_file<P: AsRef<Path>>(path: P) -> Result<Self, Error> {
1216        let mut reader = std::fs::File::open(path).map_err(Error::Io)?;
1217        let resources: Vec<Resource> =
1218            serde_json::from_reader(&mut reader).map_err(Error::Parse)?;
1219        Ok(Codec { resources })
1220    }
1221}
1222
1223#[cfg(test)]
1224mod tests {
1225    use super::*;
1226    use crate::types::{Entry, EntryStatus, Metadata, Translation};
1227    use std::collections::HashMap;
1228
1229    #[test]
1230    fn test_builder_pattern() {
1231        // Test creating an empty codec
1232        let codec = Codec::builder().build();
1233        assert_eq!(codec.resources.len(), 0);
1234
1235        // Test adding resources directly
1236        let resource1 = Resource {
1237            metadata: Metadata {
1238                language: "en".to_string(),
1239                domain: "test".to_string(),
1240                custom: std::collections::HashMap::new(),
1241            },
1242            entries: vec![Entry {
1243                id: "hello".to_string(),
1244                value: Translation::Singular("Hello".to_string()),
1245                comment: None,
1246                status: EntryStatus::Translated,
1247                custom: std::collections::HashMap::new(),
1248            }],
1249        };
1250
1251        let resource2 = Resource {
1252            metadata: Metadata {
1253                language: "fr".to_string(),
1254                domain: "test".to_string(),
1255                custom: std::collections::HashMap::new(),
1256            },
1257            entries: vec![Entry {
1258                id: "hello".to_string(),
1259                value: Translation::Singular("Bonjour".to_string()),
1260                comment: None,
1261                status: EntryStatus::Translated,
1262                custom: std::collections::HashMap::new(),
1263            }],
1264        };
1265
1266        let codec = Codec::builder()
1267            .add_resource(resource1.clone())
1268            .add_resource(resource2.clone())
1269            .build();
1270
1271        assert_eq!(codec.resources.len(), 2);
1272        assert_eq!(codec.resources[0].metadata.language, "en");
1273        assert_eq!(codec.resources[1].metadata.language, "fr");
1274    }
1275
1276    #[test]
1277    fn test_builder_validation() {
1278        // Test validation with empty language
1279        let resource_without_language = Resource {
1280            metadata: Metadata {
1281                language: "".to_string(),
1282                domain: "test".to_string(),
1283                custom: std::collections::HashMap::new(),
1284            },
1285            entries: vec![],
1286        };
1287
1288        let result = Codec::builder()
1289            .add_resource(resource_without_language)
1290            .build_and_validate();
1291
1292        assert!(result.is_err());
1293        assert!(matches!(result.unwrap_err(), Error::Validation(_)));
1294
1295        // Test validation with duplicate languages
1296        let resource1 = Resource {
1297            metadata: Metadata {
1298                language: "en".to_string(),
1299                domain: "test".to_string(),
1300                custom: std::collections::HashMap::new(),
1301            },
1302            entries: vec![],
1303        };
1304
1305        let resource2 = Resource {
1306            metadata: Metadata {
1307                language: "en".to_string(), // Duplicate language
1308                domain: "test".to_string(),
1309                custom: std::collections::HashMap::new(),
1310            },
1311            entries: vec![],
1312        };
1313
1314        let result = Codec::builder()
1315            .add_resource(resource1)
1316            .add_resource(resource2)
1317            .build_and_validate();
1318
1319        assert!(result.is_err());
1320        assert!(matches!(result.unwrap_err(), Error::Validation(_)));
1321    }
1322
1323    #[test]
1324    fn test_builder_add_resources() {
1325        let resources = vec![
1326            Resource {
1327                metadata: Metadata {
1328                    language: "en".to_string(),
1329                    domain: "test".to_string(),
1330                    custom: std::collections::HashMap::new(),
1331                },
1332                entries: vec![],
1333            },
1334            Resource {
1335                metadata: Metadata {
1336                    language: "fr".to_string(),
1337                    domain: "test".to_string(),
1338                    custom: std::collections::HashMap::new(),
1339                },
1340                entries: vec![],
1341            },
1342        ];
1343
1344        let codec = Codec::builder().add_resources(resources).build();
1345        assert_eq!(codec.resources.len(), 2);
1346        assert_eq!(codec.resources[0].metadata.language, "en");
1347        assert_eq!(codec.resources[1].metadata.language, "fr");
1348    }
1349
1350    #[test]
1351    fn test_modification_methods() {
1352        use crate::types::{EntryStatus, Translation};
1353
1354        // Create a codec with some test data
1355        let mut codec = Codec::new();
1356
1357        // Add resources
1358        let resource1 = Resource {
1359            metadata: Metadata {
1360                language: "en".to_string(),
1361                domain: "test".to_string(),
1362                custom: std::collections::HashMap::new(),
1363            },
1364            entries: vec![Entry {
1365                id: "welcome".to_string(),
1366                value: Translation::Singular("Hello".to_string()),
1367                comment: None,
1368                status: EntryStatus::Translated,
1369                custom: std::collections::HashMap::new(),
1370            }],
1371        };
1372
1373        let resource2 = Resource {
1374            metadata: Metadata {
1375                language: "fr".to_string(),
1376                domain: "test".to_string(),
1377                custom: std::collections::HashMap::new(),
1378            },
1379            entries: vec![Entry {
1380                id: "welcome".to_string(),
1381                value: Translation::Singular("Bonjour".to_string()),
1382                comment: None,
1383                status: EntryStatus::Translated,
1384                custom: std::collections::HashMap::new(),
1385            }],
1386        };
1387
1388        codec.add_resource(resource1);
1389        codec.add_resource(resource2);
1390
1391        // Test find_entries
1392        let entries = codec.find_entries("welcome");
1393        assert_eq!(entries.len(), 2);
1394        assert_eq!(entries[0].0.metadata.language, "en");
1395        assert_eq!(entries[1].0.metadata.language, "fr");
1396
1397        // Test find_entry
1398        let entry = codec.find_entry("welcome", "en");
1399        assert!(entry.is_some());
1400        assert_eq!(entry.unwrap().id, "welcome");
1401
1402        // Test find_entry_mut and update
1403        if let Some(entry) = codec.find_entry_mut("welcome", "en") {
1404            entry.value = Translation::Singular("Hello, World!".to_string());
1405            entry.status = EntryStatus::NeedsReview;
1406        }
1407
1408        // Verify the update
1409        let updated_entry = codec.find_entry("welcome", "en").unwrap();
1410        assert_eq!(updated_entry.value.to_string(), "Hello, World!");
1411        assert_eq!(updated_entry.status, EntryStatus::NeedsReview);
1412
1413        // Test update_translation
1414        codec
1415            .update_translation(
1416                "welcome",
1417                "fr",
1418                Translation::Singular("Bonjour, le monde!".to_string()),
1419                Some(EntryStatus::NeedsReview),
1420            )
1421            .unwrap();
1422
1423        // Test add_entry
1424        codec
1425            .add_entry(
1426                "new_key",
1427                "en",
1428                Translation::Singular("New message".to_string()),
1429                Some("A new message".to_string()),
1430                Some(EntryStatus::New),
1431            )
1432            .unwrap();
1433
1434        assert!(codec.has_entry("new_key", "en"));
1435        assert_eq!(codec.entry_count("en"), 2);
1436
1437        // Test remove_entry
1438        codec.remove_entry("new_key", "en").unwrap();
1439        assert!(!codec.has_entry("new_key", "en"));
1440        assert_eq!(codec.entry_count("en"), 1);
1441
1442        // Test copy_entry
1443        codec.copy_entry("welcome", "en", "fr", true).unwrap();
1444        let copied_entry = codec.find_entry("welcome", "fr").unwrap();
1445        assert_eq!(copied_entry.status, EntryStatus::New);
1446
1447        // Test languages
1448        let languages: Vec<_> = codec.languages().collect();
1449        assert_eq!(languages.len(), 2);
1450        assert!(languages.contains(&"en"));
1451        assert!(languages.contains(&"fr"));
1452
1453        // Test all_keys
1454        let keys: Vec<_> = codec.all_keys().collect();
1455        assert_eq!(keys.len(), 1);
1456        assert!(keys.contains(&"welcome"));
1457    }
1458
1459    #[test]
1460    fn test_validation() {
1461        let mut codec = Codec::new();
1462
1463        // Test validation with empty language
1464        let resource_without_language = Resource {
1465            metadata: Metadata {
1466                language: "".to_string(),
1467                domain: "test".to_string(),
1468                custom: std::collections::HashMap::new(),
1469            },
1470            entries: vec![],
1471        };
1472
1473        codec.add_resource(resource_without_language);
1474        assert!(codec.validate().is_err());
1475
1476        // Test validation with duplicate languages
1477        let mut codec = Codec::new();
1478        let resource1 = Resource {
1479            metadata: Metadata {
1480                language: "en".to_string(),
1481                domain: "test".to_string(),
1482                custom: std::collections::HashMap::new(),
1483            },
1484            entries: vec![],
1485        };
1486
1487        let resource2 = Resource {
1488            metadata: Metadata {
1489                language: "en".to_string(), // Duplicate language
1490                domain: "test".to_string(),
1491                custom: std::collections::HashMap::new(),
1492            },
1493            entries: vec![],
1494        };
1495
1496        codec.add_resource(resource1);
1497        codec.add_resource(resource2);
1498        assert!(codec.validate().is_err());
1499
1500        // Test validation with missing translations
1501        let mut codec = Codec::new();
1502        let resource1 = Resource {
1503            metadata: Metadata {
1504                language: "en".to_string(),
1505                domain: "test".to_string(),
1506                custom: std::collections::HashMap::new(),
1507            },
1508            entries: vec![Entry {
1509                id: "welcome".to_string(),
1510                value: Translation::Singular("Hello".to_string()),
1511                comment: None,
1512                status: EntryStatus::Translated,
1513                custom: std::collections::HashMap::new(),
1514            }],
1515        };
1516
1517        let resource2 = Resource {
1518            metadata: Metadata {
1519                language: "fr".to_string(),
1520                domain: "test".to_string(),
1521                custom: std::collections::HashMap::new(),
1522            },
1523            entries: vec![], // Missing welcome entry
1524        };
1525
1526        codec.add_resource(resource1);
1527        codec.add_resource(resource2);
1528        assert!(codec.validate().is_err());
1529    }
1530
1531    #[test]
1532    fn test_convert_csv_to_xcstrings() {
1533        // Test CSV to XCStrings conversion
1534        let temp_dir = tempfile::tempdir().unwrap();
1535        let input_file = temp_dir.path().join("test.csv");
1536        let output_file = temp_dir.path().join("output.xcstrings");
1537
1538        let csv_content =
1539            "key,en,fr,de\nhello,Hello,Bonjour,Hallo\nbye,Goodbye,Au revoir,Auf Wiedersehen\n";
1540        std::fs::write(&input_file, csv_content).unwrap();
1541
1542        // First, let's see what the CSV parsing produces
1543        let csv_format = CSVFormat::read_from(&input_file).unwrap();
1544        let resources = Vec::<Resource>::try_from(csv_format).unwrap();
1545        println!("CSV parsed to {} resources:", resources.len());
1546        for (i, resource) in resources.iter().enumerate() {
1547            println!(
1548                "  Resource {}: language={}, entries={}",
1549                i,
1550                resource.metadata.language,
1551                resource.entries.len()
1552            );
1553            for entry in &resource.entries {
1554                println!("    Entry: id={}, value={:?}", entry.id, entry.value);
1555            }
1556        }
1557
1558        let result = crate::converter::convert(
1559            &input_file,
1560            FormatType::CSV,
1561            &output_file,
1562            FormatType::Xcstrings,
1563        );
1564
1565        match result {
1566            Ok(()) => println!("✅ CSV to XCStrings conversion succeeded"),
1567            Err(e) => println!("❌ CSV to XCStrings conversion failed: {}", e),
1568        }
1569
1570        // Check the output file content
1571        if output_file.exists() {
1572            let content = std::fs::read_to_string(&output_file).unwrap();
1573            println!("Output file content: {}", content);
1574        }
1575
1576        // Clean up
1577        let _ = std::fs::remove_file(input_file);
1578        let _ = std::fs::remove_file(output_file);
1579    }
1580
1581    #[test]
1582    fn test_merge_resources_method() {
1583        use crate::types::{ConflictStrategy, Entry, EntryStatus, Metadata, Translation};
1584
1585        let mut codec = Codec::new();
1586
1587        // Create multiple resources for the same language (English)
1588        let resource1 = Resource {
1589            metadata: Metadata {
1590                language: "en".to_string(),
1591                domain: "domain1".to_string(),
1592                custom: HashMap::new(),
1593            },
1594            entries: vec![Entry {
1595                id: "hello".to_string(),
1596                value: Translation::Singular("Hello".to_string()),
1597                comment: None,
1598                status: EntryStatus::Translated,
1599                custom: HashMap::new(),
1600            }],
1601        };
1602
1603        let resource2 = Resource {
1604            metadata: Metadata {
1605                language: "en".to_string(),
1606                domain: "domain2".to_string(),
1607                custom: HashMap::new(),
1608            },
1609            entries: vec![Entry {
1610                id: "goodbye".to_string(),
1611                value: Translation::Singular("Goodbye".to_string()),
1612                comment: None,
1613                status: EntryStatus::Translated,
1614                custom: HashMap::new(),
1615            }],
1616        };
1617
1618        let resource3 = Resource {
1619            metadata: Metadata {
1620                language: "en".to_string(),
1621                domain: "domain3".to_string(),
1622                custom: HashMap::new(),
1623            },
1624            entries: vec![Entry {
1625                id: "hello".to_string(), // Conflict with resource1
1626                value: Translation::Singular("Hi".to_string()),
1627                comment: None,
1628                status: EntryStatus::Translated,
1629                custom: HashMap::new(),
1630            }],
1631        };
1632
1633        // Add resources to codec
1634        codec.add_resource(resource1);
1635        codec.add_resource(resource2);
1636        codec.add_resource(resource3);
1637
1638        // Test merging with Last strategy
1639        let merges_performed = codec.merge_resources(&ConflictStrategy::Last);
1640        assert_eq!(merges_performed, 1); // Should merge 1 language group
1641        assert_eq!(codec.resources.len(), 1); // Should have 1 merged resource
1642
1643        let merged_resource = &codec.resources[0];
1644        assert_eq!(merged_resource.metadata.language, "en");
1645        assert_eq!(merged_resource.entries.len(), 2); // hello + goodbye
1646
1647        // Check that the last entry for "hello" was kept (from resource3)
1648        let hello_entry = merged_resource
1649            .entries
1650            .iter()
1651            .find(|e| e.id == "hello")
1652            .unwrap();
1653        assert_eq!(hello_entry.value.plain_translation_string(), "Hi");
1654    }
1655
1656    #[test]
1657    fn test_merge_resources_method_multiple_languages() {
1658        use crate::types::{ConflictStrategy, Entry, EntryStatus, Metadata, Translation};
1659
1660        let mut codec = Codec::new();
1661
1662        // Create resources for English (multiple)
1663        let en_resource1 = Resource {
1664            metadata: Metadata {
1665                language: "en".to_string(),
1666                domain: "domain1".to_string(),
1667                custom: HashMap::new(),
1668            },
1669            entries: vec![Entry {
1670                id: "hello".to_string(),
1671                value: Translation::Singular("Hello".to_string()),
1672                comment: None,
1673                status: EntryStatus::Translated,
1674                custom: HashMap::new(),
1675            }],
1676        };
1677
1678        let en_resource2 = Resource {
1679            metadata: Metadata {
1680                language: "en".to_string(),
1681                domain: "domain2".to_string(),
1682                custom: HashMap::new(),
1683            },
1684            entries: vec![Entry {
1685                id: "goodbye".to_string(),
1686                value: Translation::Singular("Goodbye".to_string()),
1687                comment: None,
1688                status: EntryStatus::Translated,
1689                custom: HashMap::new(),
1690            }],
1691        };
1692
1693        // Create resource for French (single)
1694        let fr_resource = Resource {
1695            metadata: Metadata {
1696                language: "fr".to_string(),
1697                domain: "domain1".to_string(),
1698                custom: HashMap::new(),
1699            },
1700            entries: vec![Entry {
1701                id: "bonjour".to_string(),
1702                value: Translation::Singular("Bonjour".to_string()),
1703                comment: None,
1704                status: EntryStatus::Translated,
1705                custom: HashMap::new(),
1706            }],
1707        };
1708
1709        // Add resources to codec
1710        codec.add_resource(en_resource1);
1711        codec.add_resource(en_resource2);
1712        codec.add_resource(fr_resource);
1713
1714        // Test merging
1715        let merges_performed = codec.merge_resources(&ConflictStrategy::First);
1716        assert_eq!(merges_performed, 1); // Should merge 1 language group (English)
1717        assert_eq!(codec.resources.len(), 2); // Should have 2 resources (merged English + French)
1718
1719        // Check English resource was merged
1720        let en_resource = codec.get_by_language("en").unwrap();
1721        assert_eq!(en_resource.entries.len(), 2);
1722
1723        // Check French resource was unchanged
1724        let fr_resource = codec.get_by_language("fr").unwrap();
1725        assert_eq!(fr_resource.entries.len(), 1);
1726        assert_eq!(fr_resource.entries[0].id, "bonjour");
1727    }
1728
1729    #[test]
1730    fn test_merge_resources_method_no_merges() {
1731        use crate::types::{ConflictStrategy, Entry, EntryStatus, Metadata, Translation};
1732
1733        let mut codec = Codec::new();
1734
1735        // Create resources for different languages (no conflicts)
1736        let en_resource = Resource {
1737            metadata: Metadata {
1738                language: "en".to_string(),
1739                domain: "domain1".to_string(),
1740                custom: HashMap::new(),
1741            },
1742            entries: vec![Entry {
1743                id: "hello".to_string(),
1744                value: Translation::Singular("Hello".to_string()),
1745                comment: None,
1746                status: EntryStatus::Translated,
1747                custom: HashMap::new(),
1748            }],
1749        };
1750
1751        let fr_resource = Resource {
1752            metadata: Metadata {
1753                language: "fr".to_string(),
1754                domain: "domain1".to_string(),
1755                custom: HashMap::new(),
1756            },
1757            entries: vec![Entry {
1758                id: "bonjour".to_string(),
1759                value: Translation::Singular("Bonjour".to_string()),
1760                comment: None,
1761                status: EntryStatus::Translated,
1762                custom: HashMap::new(),
1763            }],
1764        };
1765
1766        // Add resources to codec
1767        codec.add_resource(en_resource);
1768        codec.add_resource(fr_resource);
1769
1770        // Test merging - should perform no merges
1771        let merges_performed = codec.merge_resources(&ConflictStrategy::Last);
1772        assert_eq!(merges_performed, 0); // Should merge 0 language groups
1773        assert_eq!(codec.resources.len(), 2); // Should still have 2 resources
1774
1775        // Check resources are unchanged
1776        assert!(codec.get_by_language("en").is_some());
1777        assert!(codec.get_by_language("fr").is_some());
1778    }
1779
1780    #[test]
1781    fn test_merge_resources_method_empty_codec() {
1782        let mut codec = Codec::new();
1783
1784        // Test merging empty codec
1785        let merges_performed = codec.merge_resources(&ConflictStrategy::Last);
1786        assert_eq!(merges_performed, 0);
1787        assert_eq!(codec.resources.len(), 0);
1788    }
1789
1790    #[test]
1791    fn test_extend_from_and_from_codecs() {
1792        let mut codec1 = Codec::new();
1793        let mut codec2 = Codec::new();
1794
1795        let en_resource = Resource {
1796            metadata: Metadata {
1797                language: "en".to_string(),
1798                domain: "d1".to_string(),
1799                custom: HashMap::new(),
1800            },
1801            entries: vec![Entry {
1802                id: "hello".to_string(),
1803                value: Translation::Singular("Hello".to_string()),
1804                comment: None,
1805                status: EntryStatus::Translated,
1806                custom: HashMap::new(),
1807            }],
1808        };
1809
1810        let fr_resource = Resource {
1811            metadata: Metadata {
1812                language: "fr".to_string(),
1813                domain: "d2".to_string(),
1814                custom: HashMap::new(),
1815            },
1816            entries: vec![Entry {
1817                id: "bonjour".to_string(),
1818                value: Translation::Singular("Bonjour".to_string()),
1819                comment: None,
1820                status: EntryStatus::Translated,
1821                custom: HashMap::new(),
1822            }],
1823        };
1824
1825        codec1.add_resource(en_resource);
1826        codec2.add_resource(fr_resource);
1827
1828        // extend_from
1829        let mut combined = codec1;
1830        combined.extend_from(codec2);
1831        assert_eq!(combined.resources.len(), 2);
1832
1833        // from_codecs
1834        let c = Codec::from_codecs(vec![combined.clone()]);
1835        assert_eq!(c.resources.len(), 2);
1836    }
1837
1838    #[test]
1839    fn test_merge_codecs_across_instances() {
1840        use crate::types::ConflictStrategy;
1841
1842        // Two codecs, both English with different entries -> should merge to one English with two entries
1843        let mut c1 = Codec::new();
1844        let mut c2 = Codec::new();
1845
1846        c1.add_resource(Resource {
1847            metadata: Metadata {
1848                language: "en".to_string(),
1849                domain: "d1".to_string(),
1850                custom: HashMap::new(),
1851            },
1852            entries: vec![Entry {
1853                id: "hello".to_string(),
1854                value: Translation::Singular("Hello".to_string()),
1855                comment: None,
1856                status: EntryStatus::Translated,
1857                custom: HashMap::new(),
1858            }],
1859        });
1860
1861        c2.add_resource(Resource {
1862            metadata: Metadata {
1863                language: "en".to_string(),
1864                domain: "d2".to_string(),
1865                custom: HashMap::new(),
1866            },
1867            entries: vec![Entry {
1868                id: "goodbye".to_string(),
1869                value: Translation::Singular("Goodbye".to_string()),
1870                comment: None,
1871                status: EntryStatus::Translated,
1872                custom: HashMap::new(),
1873            }],
1874        });
1875
1876        let merged = Codec::merge_codecs(vec![c1, c2], &ConflictStrategy::Last);
1877        assert_eq!(merged.resources.len(), 1);
1878        assert_eq!(merged.resources[0].metadata.language, "en");
1879        assert_eq!(merged.resources[0].entries.len(), 2);
1880    }
1881
1882    #[test]
1883    fn test_validate_placeholders_across_languages() {
1884        let mut codec = Codec::new();
1885        // English with %1$@, French with %1$s should match after normalization
1886        codec.add_resource(Resource {
1887            metadata: Metadata {
1888                language: "en".into(),
1889                domain: "d".into(),
1890                custom: HashMap::new(),
1891            },
1892            entries: vec![Entry {
1893                id: "greet".into(),
1894                value: Translation::Singular("Hello %1$@".into()),
1895                comment: None,
1896                status: EntryStatus::Translated,
1897                custom: HashMap::new(),
1898            }],
1899        });
1900        codec.add_resource(Resource {
1901            metadata: Metadata {
1902                language: "fr".into(),
1903                domain: "d".into(),
1904                custom: HashMap::new(),
1905            },
1906            entries: vec![Entry {
1907                id: "greet".into(),
1908                value: Translation::Singular("Bonjour %1$s".into()),
1909                comment: None,
1910                status: EntryStatus::Translated,
1911                custom: HashMap::new(),
1912            }],
1913        });
1914        assert!(codec.validate_placeholders(true).is_ok());
1915    }
1916
1917    #[test]
1918    fn test_validate_placeholders_mismatch() {
1919        let mut codec = Codec::new();
1920        codec.add_resource(Resource {
1921            metadata: Metadata {
1922                language: "en".into(),
1923                domain: "d".into(),
1924                custom: HashMap::new(),
1925            },
1926            entries: vec![Entry {
1927                id: "count".into(),
1928                value: Translation::Singular("%d files".into()),
1929                comment: None,
1930                status: EntryStatus::Translated,
1931                custom: HashMap::new(),
1932            }],
1933        });
1934        codec.add_resource(Resource {
1935            metadata: Metadata {
1936                language: "fr".into(),
1937                domain: "d".into(),
1938                custom: HashMap::new(),
1939            },
1940            entries: vec![Entry {
1941                id: "count".into(),
1942                value: Translation::Singular("%s fichiers".into()),
1943                comment: None,
1944                status: EntryStatus::Translated,
1945                custom: HashMap::new(),
1946            }],
1947        });
1948        assert!(codec.validate_placeholders(true).is_err());
1949    }
1950
1951    #[test]
1952    fn test_collect_placeholder_issues_non_strict_ok() {
1953        let mut codec = Codec::new();
1954        codec.add_resource(Resource {
1955            metadata: Metadata {
1956                language: "en".into(),
1957                domain: "d".into(),
1958                custom: HashMap::new(),
1959            },
1960            entries: vec![Entry {
1961                id: "count".into(),
1962                value: Translation::Singular("%d files".into()),
1963                comment: None,
1964                status: EntryStatus::Translated,
1965                custom: HashMap::new(),
1966            }],
1967        });
1968        codec.add_resource(Resource {
1969            metadata: Metadata {
1970                language: "fr".into(),
1971                domain: "d".into(),
1972                custom: HashMap::new(),
1973            },
1974            entries: vec![Entry {
1975                id: "count".into(),
1976                value: Translation::Singular("%s fichiers".into()),
1977                comment: None,
1978                status: EntryStatus::Translated,
1979                custom: HashMap::new(),
1980            }],
1981        });
1982        // Non-strict should be Ok but issues present
1983        assert!(codec.validate_placeholders(false).is_ok());
1984        let issues = codec.collect_placeholder_issues();
1985        assert!(!issues.is_empty());
1986    }
1987
1988    #[test]
1989    fn test_normalize_placeholders_in_place() {
1990        let mut codec = Codec::new();
1991        codec.add_resource(Resource {
1992            metadata: Metadata {
1993                language: "en".into(),
1994                domain: "d".into(),
1995                custom: HashMap::new(),
1996            },
1997            entries: vec![Entry {
1998                id: "g".into(),
1999                value: Translation::Singular("Hello %@ and %1$@".into()),
2000                comment: None,
2001                status: EntryStatus::Translated,
2002                custom: HashMap::new(),
2003            }],
2004        });
2005        codec.normalize_placeholders_in_place();
2006        let v = match &codec.resources[0].entries[0].value {
2007            Translation::Singular(v) => v.clone(),
2008            _ => String::new(),
2009        };
2010        assert!(v.contains("%s"));
2011        assert!(v.contains("%1$s"));
2012    }
2013
2014    #[test]
2015    fn test_normalize_placeholders_in_place_skips_stringsdict_structural_entries() {
2016        use crate::formats::stringsdict::{
2017            LOCALIZED_FORMAT_CUSTOM_KEY, VALUE_TYPE_CUSTOM_KEY, VARIABLE_NAME_CUSTOM_KEY,
2018        };
2019
2020        let mut structural_custom = HashMap::new();
2021        structural_custom.insert(
2022            LOCALIZED_FORMAT_CUSTOM_KEY.to_string(),
2023            "%#@count@".to_string(),
2024        );
2025        structural_custom.insert(VARIABLE_NAME_CUSTOM_KEY.to_string(), "count".to_string());
2026        structural_custom.insert(VALUE_TYPE_CUSTOM_KEY.to_string(), "ld".to_string());
2027
2028        let mut partial_custom = HashMap::new();
2029        partial_custom.insert(VALUE_TYPE_CUSTOM_KEY.to_string(), "lu".to_string());
2030
2031        let mut codec = Codec::new();
2032        codec.add_resource(Resource {
2033            metadata: Metadata {
2034                language: "en".into(),
2035                domain: "d".into(),
2036                custom: HashMap::new(),
2037            },
2038            entries: vec![
2039                Entry {
2040                    id: "count".into(),
2041                    value: Translation::Singular("%ld files".into()),
2042                    comment: None,
2043                    status: EntryStatus::Translated,
2044                    custom: structural_custom,
2045                },
2046                Entry {
2047                    id: "partial".into(),
2048                    value: Translation::Singular("%lu bytes".into()),
2049                    comment: None,
2050                    status: EntryStatus::Translated,
2051                    custom: partial_custom,
2052                },
2053                Entry {
2054                    id: "ordinary".into(),
2055                    value: Translation::Singular("Hello %@".into()),
2056                    comment: None,
2057                    status: EntryStatus::Translated,
2058                    custom: HashMap::new(),
2059                },
2060            ],
2061        });
2062
2063        codec.normalize_placeholders_in_place();
2064
2065        assert_eq!(
2066            codec.resources[0].entries[0].value,
2067            Translation::Singular("%ld files".into())
2068        );
2069        assert_eq!(
2070            codec.resources[0].entries[0]
2071                .custom
2072                .get(VALUE_TYPE_CUSTOM_KEY)
2073                .map(String::as_str),
2074            Some("ld")
2075        );
2076        assert_eq!(
2077            codec.resources[0].entries[1].value,
2078            Translation::Singular("%lu bytes".into())
2079        );
2080        assert_eq!(
2081            codec.resources[0].entries[2].value,
2082            Translation::Singular("Hello %s".into())
2083        );
2084    }
2085
2086    #[test]
2087    fn test_read_file_by_type_with_strict_requires_language() {
2088        let temp = tempfile::tempdir().unwrap();
2089        let input = temp.path().join("Localizable.strings");
2090        std::fs::write(&input, "\"hello\" = \"Hello\";").unwrap();
2091
2092        let mut codec = Codec::new();
2093        let err = codec
2094            .read_file_by_type_with_options(
2095                &input,
2096                FormatType::Strings(None),
2097                &ReadOptions::new().with_strict(true),
2098            )
2099            .unwrap_err();
2100        assert_eq!(err.error_code(), crate::ErrorCode::MissingLanguage);
2101    }
2102
2103    #[test]
2104    fn test_read_file_language_precedence_is_hint_then_format_then_path() {
2105        let temp = tempfile::tempdir().unwrap();
2106        let locale_directory = temp.path().join("fr.lproj");
2107        std::fs::create_dir_all(&locale_directory).unwrap();
2108        let input = locale_directory.join("Localizable.strings");
2109        std::fs::write(&input, "\"hello\" = \"Hello\";").unwrap();
2110
2111        let mut explicit_format_codec = Codec::new();
2112        explicit_format_codec
2113            .read_file_by_type_with_options(
2114                &input,
2115                FormatType::Strings(Some("de".to_string())),
2116                &ReadOptions::default(),
2117            )
2118            .unwrap();
2119        assert_eq!(
2120            explicit_format_codec.resources[0].metadata.language, "de",
2121            "the explicit format language must outrank the fr.lproj path"
2122        );
2123
2124        let mut hinted_codec = Codec::new();
2125        hinted_codec
2126            .read_file_by_type_with_options(
2127                &input,
2128                FormatType::Strings(Some("de".to_string())),
2129                &ReadOptions::new().with_language_hint(Some("es".to_string())),
2130            )
2131            .unwrap();
2132        assert_eq!(
2133            hinted_codec.resources[0].metadata.language, "es",
2134            "the read option hint must outrank both the format language and path"
2135        );
2136    }
2137
2138    #[test]
2139    fn test_read_file_with_provenance() {
2140        let temp = tempfile::tempdir().unwrap();
2141        let lproj = temp.path().join("en.lproj");
2142        std::fs::create_dir_all(&lproj).unwrap();
2143        let input = lproj.join("Localizable.strings");
2144        std::fs::write(&input, "\"hello\" = \"Hello\";").unwrap();
2145
2146        let mut codec = Codec::new();
2147        codec
2148            .read_file_by_extension_with_options(&input, &ReadOptions::new().with_provenance(true))
2149            .unwrap();
2150
2151        let provenance = crate::resource_provenance(codec.resources.first().unwrap()).unwrap();
2152        assert_eq!(
2153            provenance.source_path,
2154            Some(input.to_string_lossy().to_string())
2155        );
2156        assert_eq!(provenance.source_format, Some("strings".to_string()));
2157    }
2158}