How freenowtech/phrase-kotlin-client works
Project type and purpose
• This is a Kotlin library / CLI-style tool (“phrase-kotlin-client”) that provides a client and a sync task for the PhraseApp API v2.
• It’s not a frontend/backend web app but an SDK + build task that can be embedded in any JVM project (Spring Boot supported).
File structure
• Top-level: pom.xml, CI config (.github/workflows/mvn.yml), codecov.yml, LICENSE, README.md
• src/main/kotlin/com/freenow/apis/phraseapi/client → the core client interface, implementation, and config
• src/main/kotlin/com/freenow/apis/phraseapi/client/model → domain models (Project, Locale, Translation, etc.)
• src/main/kotlin/com/freenow/apis/phraseapi/task → the PhraseAppSyncTask that orchestrates the synchronization
• src/test/kotlin → unit and integration tests around the client and task
• No database, no UI, no webserver: core modules + integration with external API
Extract insights from README
• Purpose: fetch/sync translation resources from PhraseApp via REST API v2
• Usage: instantiate PhraseAppSyncTaskConfig, create PhraseAppSyncTask, call run()
• Supports Spring Boot 1.x/2.x (implying the client can be used as a Spring Boot task)
Main components & relationships
a. Components
• External Service: PhraseApp REST API v2
• Core Client Module
– PhraseApiClient interface
– PhraseApiClientImpl (HTTP calls)
– PhraseApiClientConfig (auth, URL)
– Model classes (Key, PhraseLocale, PhraseProject, Tags, Translation)
• Sync Orchestrator
– PhraseAppSyncTask (uses the client to fetch and process resources)
• Build & CI
– Maven (pom.xml)
– GitHub Actions workflow (mvn.yml)
– Codecov integration
• Tests
– Unit tests for client methods
– Integration tests against a mocked/real PhraseApp instance
b. Interactions
1. Developer code/config instantiates PhraseAppSyncTaskConfig
2. PhraseAppSyncTask calls PhraseApiClient methods (listProjects, listLocales, listKeys, fetchTranslations)
3. PhraseApiClientImpl issues HTTP requests to the external PhraseApp API endpoints
4. JSON responses are mapped to model objects
5. PhraseAppSyncTask writes or processes the fetched translations (e.g., saves to resources directory)
6. Maven runs tests and coverage in CI, reports back to GitHub and Codecov
c. Architectural patterns & design principles
• Separation of concerns: client interface vs implementation vs orchestration task
• Configuration-driven: client config object for injection
• Modular package structure (client vs models vs task)
• Test coverage: isolated unit tests + integration tests
d. Key technologies & libraries
• Kotlin (JVM language)
• Maven (build & dependency management)
• JUnit/TestNG or Kotlin test framework
• Jackson/Gson (JSON binding) or Spring’s RestTemplate/WebClient under the hood
• GitHub Actions (CI), Codecov
Details
• Client API call as separate interactions
• Configuration flow (where auth key and URL go)
• Test suite invoking the client in isolation vs integration tests against a stubbed/real API