feat: import Duala and Bassa vocabulary via NTeALan API

services/content-service/src/main/java/cm/afrilingua/content/client/NTeALanClient.java

@@ -0,0 +1,102 @@
+package cm.afrilingua.content.client;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Client for the NTeALan collaborative dictionary API
+ * (https://apis.ntealan.net), used to import Duala and Bassa vocabulary
+ * per cahier des charges §5.1.
+ *
+ * Uses manual JsonNode traversal rather than strict POJO/Jackson binding
+ * because the API's repeatable fields (translations.equivalent,
+ * examples.example) inconsistently serialize as either a JSON array or a
+ * bare object depending on cardinality -- an XML-to-JSON conversion
+ * artifact confirmed by inspecting real API responses. A strict
+ * List<Equivalent> binding would throw a JSON mapping exception on every
+ * entry that happens to have exactly one translation.
+ */
+@Slf4j
+@Component
+public class NTeALanClient {
+
+    private static final String BASE_URL = "https://apis.ntealan.net/ntealan/dictionaries/articles";
+
+    private final RestTemplate restTemplate;
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    public NTeALanClient(@Qualifier("externalRestTemplate") RestTemplate restTemplate) {
+        this.restTemplate = restTemplate;
+    }
+
+    public List<NTeALanWordEntry> fetchArticles(String dictionaryId, int page, int limit) {
+        String url = String.format("%s/%s?limit=%d&page=%d&sort=ASC", BASE_URL, dictionaryId, limit, page);
+
+        String rawResponse;
+        try {
+            rawResponse = restTemplate.getForObject(url, String.class);
+        } catch (Exception ex) {
+            log.error("Failed to fetch NTeALan dictionary {} page {}", dictionaryId, page, ex);
+            return List.of();
+        }
+
+        if (rawResponse == null || rawResponse.isBlank()) {
+            return List.of();
+        }
+
+        try {
+            JsonNode root = objectMapper.readTree(rawResponse);
+            JsonNode articles = root.path("articles");
+
+            List<NTeALanWordEntry> entries = new ArrayList<>();
+            for (JsonNode articleWrapper : articles) {
+                NTeALanWordEntry entry = parseEntry(articleWrapper);
+                if (entry != null) {
+                    entries.add(entry);
+                }
+            }
+            return entries;
+        } catch (Exception ex) {
+            log.error("Failed to parse NTeALan response for dictionary {} page {}", dictionaryId, page, ex);
+            return List.of();
+        }
+    }
+
+    private NTeALanWordEntry parseEntry(JsonNode articleWrapper) {
+        String radical = articleWrapper.path("radical").asText(null);
+        if (radical == null || radical.isBlank()) {
+            return null;
+        }
+
+        JsonNode articleBody = articleWrapper.path("article").path("article");
+        String grammaticalCategory = articleBody.path("type").asText(null);
+
+        String translation = extractFirstEquivalent(articleBody.path("translations").path("equivalent"));
+        if (translation == null || translation.isBlank()) {
+            return null;
+        }
+
+        return new NTeALanWordEntry(radical.trim(), translation.trim(), grammaticalCategory);
+    }
+
+    /**
+     * Handles the array-or-bare-object inconsistency: a single translation
+     * serializes as a bare object instead of a one-element array.
+     */
+    private String extractFirstEquivalent(JsonNode equivalentNode) {
+        if (equivalentNode.isArray() && !equivalentNode.isEmpty()) {
+            return equivalentNode.get(0).path("content").asText(null);
+        }
+        if (equivalentNode.isObject()) {
+            return equivalentNode.path("content").asText(null);
+        }
+        return null;
+    }
+}

services/content-service/src/main/java/cm/afrilingua/content/client/NTeALanWordEntry.java

@@ -0,0 +1,4 @@
+package cm.afrilingua.content.client;
+
+public record NTeALanWordEntry(String word, String translation, String grammaticalCategory) {
+}

services/content-service/src/main/java/cm/afrilingua/content/client/RecommendationClient.java

@@ -1,22 +1,25 @@
 package cm.afrilingua.content.client;
 
 import cm.afrilingua.content.entity.Word;
-import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.stereotype.Component;
 import org.springframework.web.client.RestClientException;
 import org.springframework.web.client.RestTemplate;
 
 @Slf4j
 @Component
-@RequiredArgsConstructor
 public class RecommendationClient {
 
     private static final String APPLY_RULE_URL =
             "http://RECOMMENDATION-SERVICE/api/recommendations/difficulty/apply-rule";
 
     private final RestTemplate restTemplate;
 
+    public RecommendationClient(@Qualifier("loadBalancedRestTemplate") RestTemplate restTemplate) {
+        this.restTemplate = restTemplate;
+    }
+
     /**
      * Calls recommendation-service to apply the deterministic tone-based
      * difficulty rule. Best-effort: any failure (service down, timeout,
@@ -55,4 +58,4 @@ private record ApplyRuleRequest(String ton1, String ton2) {
 
     private record ApplyRuleResponse(String niveau) {
     }
-}
+}

services/content-service/src/main/java/cm/afrilingua/content/config/RestTemplateConfig.java

@@ -8,11 +8,18 @@
 @Configuration
 public class RestTemplateConfig {
 
-    // @LoadBalanced lets this RestTemplate resolve "http://RECOMMENDATION-SERVICE/..."
-    // via Eureka, the same way Spring Cloud Gateway resolves "lb://RECOMMENDATION-SERVICE".
+    // Resolves service names (e.g. "RECOMMENDATION-SERVICE") via Eureka.
+    // Only for calls to other services registered in this project's discovery server.
     @Bean
     @LoadBalanced
-    public RestTemplate restTemplate() {
+    public RestTemplate loadBalancedRestTemplate() {
         return new RestTemplate();
     }
-}
+
+    // Plain RestTemplate for real external domains (e.g. apis.ntealan.net),
+    // which must never go through Eureka's service resolution.
+    @Bean
+    public RestTemplate externalRestTemplate() {
+        return new RestTemplate();
+    }
+}

services/content-service/src/main/java/cm/afrilingua/content/controller/LanguageController.java

@@ -2,8 +2,10 @@
 
 import cm.afrilingua.content.api.LanguagesApi;
 import cm.afrilingua.content.dto.CreateLanguageRequest;
+import cm.afrilingua.content.dto.ImportResult;
 import cm.afrilingua.content.dto.Language;
 import cm.afrilingua.content.service.LanguageService;
+import cm.afrilingua.content.service.NTeALanImportService;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
@@ -19,6 +21,7 @@
 public class LanguageController implements LanguagesApi {
 
     private final LanguageService languageService;
+    private final NTeALanImportService nteALanImportService;
 
     @Override
     public ResponseEntity<Language> createLanguage(CreateLanguageRequest createLanguageRequest) {
@@ -35,4 +38,13 @@ public ResponseEntity<Language> getLanguage(UUID languageId) {
     public ResponseEntity<List<Language>> listLanguages() {
         return ResponseEntity.ok(languageService.listAll());
     }
+
+    @Override
+    public ResponseEntity<ImportResult> importFromNtealan(UUID languageId, String dictionaryId) {
+        NTeALanImportService.ImportResult result = nteALanImportService.importDictionary(languageId, dictionaryId);
+        return ResponseEntity.ok(new ImportResult()
+                .imported(result.imported())
+                .skipped(result.skipped())
+                .failed(result.failed()));
+    }
 }

services/content-service/src/main/java/cm/afrilingua/content/repository/WordRepository.java

@@ -8,4 +8,5 @@
 
 public interface WordRepository extends JpaRepository<Word, UUID> {
     List<Word> findByLanguageId(UUID languageId);
+    boolean existsByLanguageIdAndWordIgnoreCase(UUID languageId, String word);
 }

services/content-service/src/main/java/cm/afrilingua/content/service/NTeALanImportService.java

@@ -0,0 +1,77 @@
+package cm.afrilingua.content.service;
+
+import cm.afrilingua.content.client.NTeALanClient;
+import cm.afrilingua.content.client.NTeALanWordEntry;
+import cm.afrilingua.content.dto.CreateWordRequest;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.List;
+import java.util.UUID;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class NTeALanImportService {
+
+    private static final int PAGE_SIZE = 100;
+    // Safety net: stops the loop even if the API misbehaves and never
+    // returns an empty page (e.g. due to an unexpected upstream bug).
+    private static final int MAX_PAGES = 50;
+
+    private final NTeALanClient nteALanClient;
+    private final WordService wordService;
+    private final LanguageService languageService;
+
+    /**
+     * Imports every article from a NTeALan dictionary into the given
+     * language, paginating through the full dictionary. Idempotent: words
+     * already present for this language (case-insensitive) are skipped
+     * rather than duplicated, so this method is safe to re-run.
+     */
+    public ImportResult importDictionary(UUID languageId, String dictionaryId) {
+        // Fail fast with a 404 before starting the batch, rather than
+        // discovering a bad languageId only after the first word attempt.
+        languageService.getEntityById(languageId);
+
+        int imported = 0;
+        int skipped = 0;
+        int failed = 0;
+
+        for (int page = 1; page <= MAX_PAGES; page++) {
+            List<NTeALanWordEntry> entries = nteALanClient.fetchArticles(dictionaryId, page, PAGE_SIZE);
+            if (entries.isEmpty()) {
+                break;
+            }
+
+            for (NTeALanWordEntry entry : entries) {
+                try {
+                    if (wordService.wordExists(languageId, entry.word())) {
+                        skipped++;
+                        continue;
+                    }
+
+                    CreateWordRequest request = new CreateWordRequest()
+                            .word(entry.word())
+                            .translation(entry.translation())
+                            .grammaticalCategory(entry.grammaticalCategory());
+
+                    wordService.create(languageId, request);
+                    imported++;
+                } catch (Exception ex) {
+                    log.warn("Failed to import NTeALan word '{}' for dictionary {}", entry.word(), dictionaryId, ex);
+                    failed++;
+                }
+            }
+        }
+
+        log.info("NTeALan import complete for dictionary {}: {} imported, {} skipped, {} failed",
+                dictionaryId, imported, skipped, failed);
+
+        return new ImportResult(imported, skipped, failed);
+    }
+
+    public record ImportResult(int imported, int skipped, int failed) {
+    }
+}

services/content-service/src/main/java/cm/afrilingua/content/service/WordService.java

@@ -48,7 +48,7 @@ public cm.afrilingua.content.dto.Word create(UUID languageId, CreateWordRequest
     /**
      * Classification priority:
      * 1. An explicit difficultyLevel in the request always wins (manual override).
-     * 2. If nbSyllabes/tone1/tone2 are all provided, ask recommendation-service.
+     * 2. If tone1/tone2 are both provided, ask recommendation-service.
      * 3. Otherwise, default to BEGINNER — unchanged from the original behavior,
      *    for languages/words without tonal annotation (e.g. Duala, Bassa).
      */
@@ -83,6 +83,11 @@ public List<cm.afrilingua.content.dto.Word> listByLanguage(UUID languageId) {
                 .collect(Collectors.toList());
     }
 
+    /** Used by NTeALanImportService to skip words already imported, keeping re-runs idempotent. */
+    public boolean wordExists(UUID languageId, String word) {
+        return wordRepository.existsByLanguageIdAndWordIgnoreCase(languageId, word);
+    }
+
     private cm.afrilingua.content.dto.Word toDto(Word word) {
         return new cm.afrilingua.content.dto.Word()
                 .id(word.getId())
@@ -101,4 +106,4 @@ private cm.afrilingua.content.dto.Word toDto(Word word) {
                         ? cm.afrilingua.content.dto.Word.Tone2Enum.fromValue(word.getTone2())
                         : null);
     }
-}
+}