feat(l10n): support localized value lookup and wrapper caller discovery in usages command

The `l10n usages` command now resolves translated string values (e.g., "进场特效")
to their l10n keys, and discovers code that references those keys through wrapper
binding call sites — not just SwiftUI view nodes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ahavili

grapha/src/app/index.rs

@@ -38,6 +38,23 @@ pub(crate) fn load_graph_for_l10n(path: &Path) -> anyhow::Result<grapha_core::gr
     .context("no index found — run `grapha index` first")
 }
 
+pub(crate) fn load_graph_for_l10n_usages(path: &Path) -> anyhow::Result<grapha_core::graph::Graph> {
+    use grapha_core::graph::EdgeKind;
+    let db_path = path.join(".grapha/grapha.db");
+    let s = store::sqlite::SqliteStore::new(db_path);
+    s.load_filtered(
+        Some(&[
+            EdgeKind::Contains,
+            EdgeKind::TypeRef,
+            EdgeKind::Calls,
+            EdgeKind::Implements,
+            EdgeKind::Uses,
+        ]),
+        Some("l10n."),
+    )
+    .context("no index found — run `grapha index` first")
+}
+
 fn store_file_path(format: &str, store_path: &Path) -> anyhow::Result<PathBuf> {
     match format {
         "json" => Ok(store_path.join("graph.json")),

grapha/src/app/query.rs

@@ -9,7 +9,7 @@ use crate::{
     SymbolCommands, assets, cache, changes, config, fields, localization, query, render, search,
 };
 
-use super::index::{load_graph, load_graph_for_l10n, open_search_index};
+use super::index::{load_graph, load_graph_for_l10n, load_graph_for_l10n_usages, open_search_index};
 
 fn query_cache_key(parts: &[&str]) -> String {
     parts.join("\0")
@@ -427,7 +427,7 @@ pub(crate) fn handle_l10n_command(
             }
 
             let render_options = render_options.with_fields(resolve_field_set(&fields, &path));
-            let graph = load_graph_for_l10n(&path)?;
+            let graph = load_graph_for_l10n_usages(&path)?;
             let catalogs = localization::load_catalog_index(&path)?;
             let result = query::usages::query_usages(&graph, &catalogs, &key, table.as_deref());
 

grapha/src/localization.rs

@@ -36,6 +36,8 @@ pub struct LocalizationCatalogRecord {
     pub status: String,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub comment: Option<String>,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub translations: BTreeMap<String, String>,
 }
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
@@ -123,6 +125,7 @@ pub struct LocalizationCatalogIndex {
     records: Vec<LocalizationCatalogRecord>,
     by_table_key: HashMap<(String, String), Vec<usize>>,
     by_key: HashMap<String, Vec<usize>>,
+    by_value: HashMap<String, Vec<usize>>,
 }
 
 impl LocalizationCatalogIndex {
@@ -136,6 +139,17 @@ impl LocalizationCatalogIndex {
             .entry(record.key.clone())
             .or_default()
             .push(index);
+        if !record.source_value.is_empty() {
+            self.by_value
+                .entry(record.source_value.clone())
+                .or_default()
+                .push(index);
+        }
+        for value in record.translations.values() {
+            if !value.is_empty() {
+                self.by_value.entry(value.clone()).or_default().push(index);
+            }
+        }
         self.records.push(record);
     }
 
@@ -167,6 +181,16 @@ impl LocalizationCatalogIndex {
             .cloned()
             .collect()
     }
+
+    pub fn records_for_value(&self, value: &str) -> Vec<LocalizationCatalogRecord> {
+        self.by_value
+            .get(value)
+            .into_iter()
+            .flatten()
+            .filter_map(|index| self.records.get(*index))
+            .cloned()
+            .collect()
+    }
 }
 
 pub fn build_and_save_catalog_snapshot(
@@ -240,6 +264,23 @@ fn build_catalog_snapshot(
         let catalog_file = path_relative_to_root(&root, &catalog.path);
         let catalog_dir = path_to_snapshot_string(&path_relative_to_root(&root, &catalog.base_dir));
 
+        let mut translations_by_key: HashMap<String, BTreeMap<String, String>> = HashMap::new();
+        for resource in &codec.resources {
+            let lang = &resource.metadata.language;
+            if lang == &source_language {
+                continue;
+            }
+            for entry in &resource.entries {
+                let value = translation_plain_string(&entry.value);
+                if !value.is_empty() {
+                    translations_by_key
+                        .entry(entry.id.clone())
+                        .or_default()
+                        .insert(lang.clone(), value);
+                }
+            }
+        }
+
         for entry in &source_resource.entries {
             records.push(LocalizationCatalogRecord {
                 table: table.clone(),
@@ -253,6 +294,9 @@ fn build_catalog_snapshot(
                     .trim_matches('"')
                     .to_string(),
                 comment: entry.comment.clone(),
+                translations: translations_by_key
+                    .remove(&entry.id)
+                    .unwrap_or_default(),
             });
         }
     }
@@ -1053,6 +1097,108 @@ mod tests {
         );
     }
 
+    #[test]
+    fn lookup_by_source_value() {
+        let index = LocalizationCatalogIndex::from_records(vec![LocalizationCatalogRecord {
+            table: "Localizable".to_string(),
+            key: "entrance_effect".to_string(),
+            catalog_file: "Localizable.xcstrings".to_string(),
+            catalog_dir: ".".to_string(),
+            source_language: "zh-Hans".to_string(),
+            source_value: "进场特效".to_string(),
+            status: "translated".to_string(),
+            comment: None,
+            translations: BTreeMap::new(),
+        }]);
+
+        assert!(index.records_for_key("进场特效").is_empty());
+
+        let records = index.records_for_value("进场特效");
+        assert_eq!(records.len(), 1);
+        assert_eq!(records[0].key, "entrance_effect");
+    }
+
+    #[test]
+    fn lookup_by_translation_value() {
+        let mut translations = BTreeMap::new();
+        translations.insert("zh-Hans".to_string(), "欢迎".to_string());
+        translations.insert("fr".to_string(), "Bienvenue".to_string());
+
+        let index = LocalizationCatalogIndex::from_records(vec![LocalizationCatalogRecord {
+            table: "Localizable".to_string(),
+            key: "welcome_title".to_string(),
+            catalog_file: "Localizable.xcstrings".to_string(),
+            catalog_dir: ".".to_string(),
+            source_language: "en".to_string(),
+            source_value: "Welcome".to_string(),
+            status: "translated".to_string(),
+            comment: None,
+            translations,
+        }]);
+
+        assert!(index.records_for_key("欢迎").is_empty());
+
+        let records = index.records_for_value("欢迎");
+        assert_eq!(records.len(), 1);
+        assert_eq!(records[0].key, "welcome_title");
+
+        let records = index.records_for_value("Bienvenue");
+        assert_eq!(records.len(), 1);
+        assert_eq!(records[0].key, "welcome_title");
+
+        let records = index.records_for_value("Welcome");
+        assert_eq!(records.len(), 1);
+        assert_eq!(records[0].key, "welcome_title");
+    }
+
+    #[test]
+    fn snapshot_stores_non_source_translations() {
+        let dir = tempfile::tempdir().unwrap();
+        let store_dir = dir.path().join(".grapha");
+        let file = dir.path().join("Localizable.xcstrings");
+        fs::write(
+            &file,
+            r#"{
+              "sourceLanguage" : "en",
+              "strings" : {
+                "welcome_title" : {
+                  "localizations" : {
+                    "en" : {
+                      "stringUnit" : {
+                        "state" : "translated",
+                        "value" : "Welcome"
+                      }
+                    },
+                    "zh-Hans" : {
+                      "stringUnit" : {
+                        "state" : "translated",
+                        "value" : "欢迎"
+                      }
+                    }
+                  }
+                }
+              },
+              "version" : "1.0"
+            }"#,
+        )
+        .unwrap();
+
+        build_and_save_catalog_snapshot(dir.path(), &store_dir).unwrap();
+        let index = load_catalog_index_from_store(&store_dir).unwrap();
+
+        let records = index.records_for_key("welcome_title");
+        assert_eq!(records.len(), 1);
+        assert_eq!(records[0].source_value, "Welcome");
+        assert_eq!(
+            records[0].translations.get("zh-Hans").map(String::as_str),
+            Some("欢迎")
+        );
+
+        let by_value = index.records_for_value("欢迎");
+        assert_eq!(by_value.len(), 1);
+        assert_eq!(by_value[0].key, "welcome_title");
+    }
+
     #[test]
     fn builds_and_loads_strings_catalogs() {
         let dir = tempfile::tempdir().unwrap();
@@ -1223,6 +1369,7 @@ mod tests {
                 source_value: "Auth".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
             LocalizationCatalogRecord {
                 table: "Localizable".to_string(),
@@ -1233,6 +1380,7 @@ mod tests {
                 source_value: "Profile".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
         ];
 
@@ -1256,6 +1404,7 @@ mod tests {
                 source_value: "A".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
             LocalizationCatalogRecord {
                 table: "Localizable".to_string(),
@@ -1266,6 +1415,7 @@ mod tests {
                 source_value: "B".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
         ];
 
@@ -1370,6 +1520,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         }]);
 
         let resolution = resolve_usage(
@@ -1482,6 +1633,7 @@ mod tests {
             source_value: "Share room".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         }]);
 
         let resolution = resolve_usage(
@@ -1603,6 +1755,7 @@ mod tests {
                 source_value: "The ID you entered does not exist".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
             LocalizationCatalogRecord {
                 table: "Localizable".to_string(),
@@ -1613,6 +1766,7 @@ mod tests {
                 source_value: "List is empty".to_string(),
                 status: "translated".to_string(),
                 comment: None,
+                translations: BTreeMap::new(),
             },
         ]);
 
@@ -1675,6 +1829,7 @@ mod tests {
             source_value: "Tournament".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         }]);
 
         let resolution = resolve_usage(

grapha/src/main.rs

@@ -340,9 +340,9 @@ enum L10nCommands {
         #[arg(long)]
         fields: Option<String>,
     },
-    /// Find SwiftUI usage sites for a localization key
+    /// Find SwiftUI usage sites for a localization key or translated value
     Usages {
-        /// Localization key
+        /// Localization key or translated string value
         key: String,
         /// Optional table/catalog name
         #[arg(long)]

grapha/src/query/localize.rs

@@ -422,6 +422,7 @@ mod tests {
     use super::*;
     use crate::localization::LocalizationCatalogRecord;
     use grapha_core::graph::{Edge, EdgeKind, NodeKind, Span, Visibility};
+    use std::collections::BTreeMap;
     use std::collections::HashMap as StdHashMap;
     use std::path::PathBuf;
 
@@ -501,6 +502,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         });
 
         let result = query_localize(&graph, &catalogs, "body").unwrap();
@@ -571,6 +573,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         });
 
         let result = query_localize(&graph, &catalogs, "welcomeTitle").unwrap();
@@ -641,6 +644,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         });
 
         let result = query_localize(&graph, &catalogs, "wrapper").unwrap();
@@ -797,6 +801,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         });
 
         let result = query_localize(&graph, &catalogs, "welcomeTitle").unwrap();
@@ -846,6 +851,7 @@ mod tests {
             source_value: "Welcome".to_string(),
             status: "translated".to_string(),
             comment: None,
+            translations: BTreeMap::new(),
         });
 
         let result = query_localize(&graph, &catalogs, "welcomeTitle").unwrap();