ferrocat/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2#![warn(missing_docs, rustdoc::broken_intra_doc_links)]
3//! Public Rust entry point for the `ferrocat` workspace.
4//!
5//! This crate re-exports the primary API surface from the lower-level
6//! `ferrocat-po` and `ferrocat-icu` crates so application code can depend on a
7//! single package.
8//!
9//! # Feature flags
10//!
11//! The default feature set is `full`, which enables the complete current API
12//! surface through `catalog` and `serde`.
13//!
14//! - `catalog` exposes high-level catalog parsing, updates, combining, audits,
15//!   machine-translation metadata, plural handling, FCL storage, and runtime
16//!   artifact compilation.
17//! - `serde` enables serde support in the re-exported `ferrocat-po` and
18//!   `ferrocat-icu` types.
19//! - `compile`, `mt`, and `plurals` are reserved subsystem aliases. Today they
20//!   imply `catalog`; they do not reduce or split the catalog API surface.
21//!
22//! Use `default-features = false` for low-level PO and ICU parsing without the
23//! catalog layer. Enabling `compile`, `mt`, or `plurals` currently has the same
24//! dependency effect as enabling `catalog`.
25//!
26//! # Examples
27//!
28//! ```rust
29//! use ferrocat::{icu, po};
30//!
31//! let po = po::parse_po("msgid \"Hello\"\nmsgstr \"Hallo\"\n")?;
32//! let icu = icu::parse_icu("Hello {name}")?;
33//!
34//! assert_eq!(po.items[0].msgid, "Hello");
35//! assert_eq!(icu.nodes.len(), 2);
36//! # Ok::<(), Box<dyn std::error::Error>>(())
37//! ```
38//!
39//! ```rust
40//! use ferrocat::catalog::{
41//!     CompileSelectedCatalogArtifactOptions, CompiledCatalogIdIndex, CompiledKeyStrategy,
42//!     ParseCatalogOptions, compile_catalog_artifact_selected, parse_catalog,
43//! };
44//!
45//! let source = parse_catalog(
46//!     ParseCatalogOptions::new("msgid \"Hello\"\nmsgstr \"Hello\"\n", "en").with_locale("en"),
47//! )?
48//! .into_normalized_view()?;
49//! let requested = parse_catalog(
50//!     ParseCatalogOptions::new("msgid \"Hello\"\nmsgstr \"Hallo\"\n", "en").with_locale("de"),
51//! )?
52//! .into_normalized_view()?;
53//! let index = CompiledCatalogIdIndex::new(&[&requested, &source], CompiledKeyStrategy::FerrocatV1)?;
54//! let compiled_ids = index.iter().map(|(id, _)| id).collect::<Vec<_>>();
55//! let compiled = compile_catalog_artifact_selected(
56//!     &[&requested, &source],
57//!     &index,
58//!     &CompileSelectedCatalogArtifactOptions::new("de", "en", &compiled_ids),
59//! )?;
60//!
61//! assert_eq!(compiled.messages.len(), 1);
62//! # Ok::<(), Box<dyn std::error::Error>>(())
63//! ```
64//!
65//! ```rust
66//! use ferrocat::catalog::{
67//!     CatalogAuditOptions, ParseCatalogOptions, audit_catalogs, parse_catalog,
68//! };
69//!
70//! let source = parse_catalog(
71//!     ParseCatalogOptions::new("msgid \"Checkout\"\nmsgstr \"Checkout\"\n", "en").with_locale("en"),
72//! )?
73//! .into_normalized_view()?;
74//! let target = parse_catalog(ParseCatalogOptions::new("", "en").with_locale("de"))?
75//! .into_normalized_view()?;
76//! let report = audit_catalogs(&[&source, &target], &CatalogAuditOptions::new("en"))?;
77//!
78//! assert!(report.has_errors());
79//! # Ok::<(), Box<dyn std::error::Error>>(())
80//! ```
81
82/// High-level catalog maintenance, audit, and runtime artifact APIs.
83#[cfg(feature = "catalog")]
84#[cfg_attr(docsrs, doc(cfg(feature = "catalog")))]
85pub mod catalog {
86    pub use ferrocat_po::diagnostic_codes;
87    pub use ferrocat_po::{
88        AiProvenance, ApiError, COMPILED_CATALOG_ARTIFACT_SCHEMA_VERSION, CatalogAuditChecks,
89        CatalogAuditDiagnostic, CatalogAuditIcuOptions, CatalogAuditMessageRef,
90        CatalogAuditOptions, CatalogAuditReport, CatalogAuditSummary, CatalogCombineInput,
91        CatalogCombineResult, CatalogCombineSelection, CatalogCombineStats,
92        CatalogConflictStrategy, CatalogCoverageMessage, CatalogCoverageOptions,
93        CatalogCoverageReport, CatalogFileCombineResult, CatalogFileFormat, CatalogLocaleCoverage,
94        CatalogLocaleReview, CatalogMachineTranslationMessage, CatalogMachineTranslationReview,
95        CatalogMachineTranslationStatus, CatalogMessage, CatalogMessageKey, CatalogMessageStatus,
96        CatalogMode, CatalogOrigin, CatalogReviewOptions, CatalogReviewReport,
97        CatalogReviewSummary, CatalogReviewTranslation, CatalogSemantics, CatalogSourceChange,
98        CatalogSourceChangeKind, CatalogSourceChangeReport, CatalogStats, CatalogStorageFormat,
99        CatalogTranslationChange, CatalogTranslationChangeReport, CatalogUpdateInput,
100        CatalogUpdateResult, CombineCatalogFilesOptions, CombineCatalogOptions,
101        CompileCatalogArtifactIcuOptions, CompileCatalogArtifactOptions,
102        CompileCatalogArtifactReportOptions, CompileCatalogArtifactReportSelection,
103        CompileCatalogOptions, CompileSelectedCatalogArtifactOptions, CompiledCatalog,
104        CompiledCatalogArtifact, CompiledCatalogArtifactReport, CompiledCatalogDiagnostic,
105        CompiledCatalogIdDescription, CompiledCatalogIdIndex, CompiledCatalogMissingMessage,
106        CompiledCatalogProvenanceReport, CompiledCatalogPseudolocalizationOptions,
107        CompiledCatalogResolution, CompiledCatalogResolutionKind, CompiledCatalogTranslationKind,
108        CompiledCatalogUnavailableId, CompiledKeyStrategy, CompiledMessage, CompiledTranslation,
109        DescribeCompiledIdsReport, Diagnostic, DiagnosticCode, DiagnosticSeverity,
110        EffectiveTranslation, EffectiveTranslationRef, ExtractedMessage, ExtractedPluralMessage,
111        ExtractedSingularMessage, IcuFormatterSupportPolicy, IcuPseudolocalizationOptions,
112        IcuSyntaxPolicy, MachineMetadata, NormalizedParsedCatalog, ObsoleteInfo, ObsoleteStrategy,
113        OrderBy, ParseCatalogOptions, ParsedCatalog, PlaceholderCommentMode, PluralEncoding,
114        PluralSource, PoVec, RenderOptions, SourceExtractedMessage, TranslationShape,
115        UpdateCatalogFileOptions, UpdateCatalogOptions, audit_catalogs, combine_catalog_files,
116        combine_catalogs, compile_catalog_artifact, compile_catalog_artifact_report,
117        compile_catalog_artifact_selected, compiled_key, machine_translation_hash,
118        measure_catalog_coverage, parse_catalog, pseudolocalize_compiled_catalog_artifact,
119        review_catalogs, update_catalog, update_catalog_file,
120    };
121}
122
123/// ICU MessageFormat parsing, analysis, compatibility, and metadata APIs.
124pub mod icu {
125    pub use ferrocat_icu::diagnostic_codes;
126    pub use ferrocat_icu::{
127        DiagnosticCode, IcuAnalysis, IcuArgument, IcuArgumentKind, IcuCompatibilityOptions,
128        IcuCompatibilityReport, IcuDiagnostic, IcuDiagnosticSeverity, IcuErrorKind, IcuFormatter,
129        IcuFormatterSupport, IcuMessage, IcuNode, IcuOption, IcuParseError, IcuParserOptions,
130        IcuPluralKind, IcuPluralSummary, IcuPosition, IcuPseudolocalizationOptions,
131        IcuSelectSummary, IcuStyleKind, IcuTagSummary, MessageArgumentFormatMetadata,
132        MessageArgumentKind, MessageArgumentMetadata, MessageArgumentMetadataInput,
133        MessageFormatStyleKind, MessageMetadata, MessageMetadataDiagnostic, MessageMetadataInput,
134        MessageMetadataValidationReport, MessageOriginMetadata, MessageSelectorKind,
135        MessageSelectorMetadata, analyze_icu, compare_icu_messages,
136        derive_message_metadata_from_icu, extract_argument_names, extract_tag_names,
137        extract_variables, has_plural, has_select, has_select_ordinal, has_tag,
138        normalize_message_metadata, parse_icu, parse_icu_with_options, pseudolocalize_icu,
139        pseudolocalize_icu_message, stringify_icu, validate_icu, validate_icu_formatter_support,
140        validate_icu_formatter_support_from_analysis, validate_message_metadata,
141    };
142}
143
144/// Low-level PO parsing, serialization, and text merge APIs.
145pub mod po {
146    pub use ferrocat_po::diagnostic_codes;
147    pub use ferrocat_po::{
148        BorrowedHeader, BorrowedMsgStr, BorrowedPoFile, BorrowedPoItem, Header, MergeMessageInput,
149        MsgStr, MsgStrIter, ParseError, ParsePosition, PoFile, PoItem, PoVec, SerializeOptions,
150        escape_string, extract_quoted, extract_quoted_cow, merge_catalog, parse_po,
151        parse_po_borrowed, parse_po_bytes, stringify_po, unescape_string,
152    };
153}
154
155pub use ferrocat_icu::{
156    IcuAnalysis, IcuArgument, IcuArgumentKind, IcuCompatibilityOptions, IcuCompatibilityReport,
157    IcuDiagnostic, IcuDiagnosticSeverity, IcuErrorKind, IcuFormatter, IcuFormatterSupport,
158    IcuMessage, IcuNode, IcuOption, IcuParseError, IcuParserOptions, IcuPluralKind,
159    IcuPluralSummary, IcuPosition, IcuPseudolocalizationOptions, IcuSelectSummary, IcuStyleKind,
160    IcuTagSummary, MessageArgumentFormatMetadata, MessageArgumentKind, MessageArgumentMetadata,
161    MessageArgumentMetadataInput, MessageFormatStyleKind, MessageMetadata,
162    MessageMetadataDiagnostic, MessageMetadataInput, MessageMetadataValidationReport,
163    MessageOriginMetadata, MessageSelectorKind, MessageSelectorMetadata, analyze_icu,
164    compare_icu_messages, derive_message_metadata_from_icu, extract_argument_names,
165    extract_tag_names, extract_variables, has_plural, has_select, has_select_ordinal, has_tag,
166    normalize_message_metadata, parse_icu, parse_icu_with_options, pseudolocalize_icu,
167    pseudolocalize_icu_message, stringify_icu, validate_icu, validate_icu_formatter_support,
168    validate_icu_formatter_support_from_analysis, validate_message_metadata,
169};
170
171#[cfg(feature = "catalog")]
172#[cfg_attr(docsrs, doc(cfg(feature = "catalog")))]
173/// JSON schema version emitted by [`CompiledCatalogArtifact`] serialization.
174pub const COMPILED_CATALOG_ARTIFACT_SCHEMA_VERSION: u16 =
175    ferrocat_po::COMPILED_CATALOG_ARTIFACT_SCHEMA_VERSION;
176
177#[cfg(feature = "catalog")]
178#[cfg_attr(docsrs, doc(cfg(feature = "catalog")))]
179pub use ferrocat_po::{
180    AiProvenance, ApiError, CatalogAuditChecks, CatalogAuditDiagnostic, CatalogAuditIcuOptions,
181    CatalogAuditMessageRef, CatalogAuditOptions, CatalogAuditReport, CatalogAuditSummary,
182    CatalogCombineInput, CatalogCombineResult, CatalogCombineSelection, CatalogCombineStats,
183    CatalogConflictStrategy, CatalogCoverageMessage, CatalogCoverageOptions, CatalogCoverageReport,
184    CatalogFileCombineResult, CatalogFileFormat, CatalogLocaleCoverage, CatalogLocaleReview,
185    CatalogMachineTranslationMessage, CatalogMachineTranslationReview,
186    CatalogMachineTranslationStatus, CatalogMessage, CatalogMessageKey, CatalogMessageStatus,
187    CatalogMode, CatalogOrigin, CatalogReviewOptions, CatalogReviewReport, CatalogReviewSummary,
188    CatalogReviewTranslation, CatalogSemantics, CatalogSourceChange, CatalogSourceChangeKind,
189    CatalogSourceChangeReport, CatalogStats, CatalogStorageFormat, CatalogTranslationChange,
190    CatalogTranslationChangeReport, CatalogUpdateInput, CatalogUpdateResult,
191    CombineCatalogFilesOptions, CombineCatalogOptions, CompileCatalogArtifactIcuOptions,
192    CompileCatalogArtifactOptions, CompileCatalogArtifactReportOptions,
193    CompileCatalogArtifactReportSelection, CompileCatalogOptions,
194    CompileSelectedCatalogArtifactOptions, CompiledCatalog, CompiledCatalogArtifact,
195    CompiledCatalogArtifactReport, CompiledCatalogDiagnostic, CompiledCatalogIdDescription,
196    CompiledCatalogIdIndex, CompiledCatalogMissingMessage, CompiledCatalogProvenanceReport,
197    CompiledCatalogPseudolocalizationOptions, CompiledCatalogResolution,
198    CompiledCatalogResolutionKind, CompiledCatalogTranslationKind, CompiledCatalogUnavailableId,
199    CompiledKeyStrategy, CompiledMessage, CompiledTranslation, DescribeCompiledIdsReport,
200    Diagnostic, DiagnosticCode, DiagnosticSeverity, EffectiveTranslation, EffectiveTranslationRef,
201    ExtractedMessage, ExtractedPluralMessage, ExtractedSingularMessage, IcuFormatterSupportPolicy,
202    IcuSyntaxPolicy, MachineMetadata, NormalizedParsedCatalog, ObsoleteInfo, ObsoleteStrategy,
203    OrderBy, ParseCatalogOptions, ParsedCatalog, PlaceholderCommentMode, PluralEncoding,
204    PluralSource, RenderOptions, SourceExtractedMessage, TranslationShape,
205    UpdateCatalogFileOptions, UpdateCatalogOptions, audit_catalogs, combine_catalog_files,
206    combine_catalogs, compile_catalog_artifact, compile_catalog_artifact_report,
207    compile_catalog_artifact_selected, compiled_key, machine_translation_hash,
208    measure_catalog_coverage, parse_catalog, pseudolocalize_compiled_catalog_artifact,
209    review_catalogs, update_catalog, update_catalog_file,
210};
211pub use ferrocat_po::{
212    BorrowedHeader, BorrowedMsgStr, BorrowedPoFile, BorrowedPoItem, Header, MergeMessageInput,
213    MsgStr, MsgStrIter, ParseError, ParsePosition, PoFile, PoItem, PoVec, SerializeOptions,
214    escape_string, extract_quoted, extract_quoted_cow, merge_catalog, parse_po, parse_po_borrowed,
215    parse_po_bytes, stringify_po, unescape_string,
216};
ferrocat/lib.rs

ferrocat/
lib.rs
