Recently, I had the idea to start building my new app: a Mandarin dictionary specifically for Traditional Mandarin Chinese.
The Problem with Existing Tools
I have been learning Taiwanese Mandarin for 4 years now as a hobby, using tools like Anki and YouTube, along with some books I got from my Taiwanese friends. I noticed that there aren’t many good Mandarin dictionaries available on iOS apart from Pleco. While Pleco is useful, it is primarily a bilingual dictionary, meaning it translates terms from English to Chinese and vice versa.
I really prefer using monolingual dictionaries. Reading definitions in Chinese (made for native speakers) is a great way of challenging myself and practicing my Chinese skills even more. My only workaround was to use a tool like Gemini, asking it to define a word using Chinese, but I wanted to use a dedicated, real dictionary.
I researched the most popular online dictionaries for Taiwanese Mandarin, and every time I looked it up, one dictionary consistently came up: The MOE Taiwanese Dictionary, published by the Taiwanese Government. I started using their website, but I wanted a native iOS app. Unfortunately, the apps available on the App Store that used this data hadn’t been updated in over 10 years.
This led me to want to build a modern application using SwiftUI. Luckily, I found a GitHub repository containing the dictionary data in JSON format and started with the development of the app.
Understanding the JSON data and defining the schema
To make sure my database could handle the complexity of Chinese dictionary entries, I started by analyzing some entries in the JSON file. One of these entries I analyzed was the character “行” (xíng, háng, etc), which has multiple readings (heteronyms), and each reading can have distinct meanings. This helped me to define the one-to-many relationships for the data.
Analyzing a Sample Entry
First of all, we import the json library in Python and open the dictionary file:
import jsonwith open("dict-revised.json", encoding="utf-8") as f: items = json.load(f)
At this point, the variable items is a Python object representing the JSON file (a list of dictionaries.)
Why UTF-8?
All files are stored as bytes on disk so to read then we need to decode those bytes. UTF-8 is a common text encoding used to represent all unicode characters. Without specifying it, Python might use a default encoding which can vary by system and reading non-ASCII characters could produce wrong characters.
Now, let’s get some random elements from the middle of the list:
To understand this line, let’s suppose our JSON has 100 entries:
len(items) // 4: Floor divides 100 (list length) by 4 to get the index 1/4 into the list. ⌊4100⌋=⌊25⌋=25
3*len(items)//4: Multiplies 100 (list length) by 3 and then floor divides by 4 giving the index 3/4 into the list. ⌊43⋅100⌋=⌊4300⌋=⌊75⌋=75
Slice items[start:end]: In our case the slice is items[25:75] which represents a list ranging elements with indexes 25 through 74. (see: Slicing)
random.sample(sequence, k): Where k is the number of elements to get from the sequence. In our case, we are getting 3 elements. S=x∗25,x∗26,…,x_74 By running this script, we can get three random entries to analyze.
Now, let’s try to imagine how each entry structure is going to look like. I will use the character “行” as an example:
Now, we can start defining a relational database schema in SQLite. First, we establish a connection to our database file dictionary.db, using Python’s sqlite3 module. The connection object can be seen as an open pipe or session to the database, and the cursor acts as the tool we use to send SQL commands through that connection. We will use it to execute SQL statements like creating tables and inserting data:
Then, we loop through the list of dictionaries where each dictionary is an entry:
for entry in items:
Now, for each entry:
INSERT INTO entry tells SQLite “I want to add a new row to the table entry”.
(title, radical, stroke_count, non_radical_stroke_count) specifies which columns we are filling in this row.
VALUES (?, ?, ?, ?) are placeholders for the actual values (it will be filled with the tuple we pass)
The tuple of values consists of each of the corresponding columns in the table. It gets the values with the key "title", radical, etc from the JSON dictionary entry or None if it is missing.
After inserting a row into the table, lastrowid stores the auto-increment ID assigned to the entry by SQLite:
entry_id = cur.lastrowid
Now, we do the same for the list of heteronyms into from each entry:
for het in entry.get("heteronyms", []): cur.execute( "INSERT INTO heteronym (entry_id, pinyin, bopomofo) VALUES (?, ?, ?)", ( entry_id, het.get("pinyin"), het.get("bopomofo") ) ) heteronym_id = cur.lastrowid
Now, for the definitions:
As example and quote are lists, we need to convert them into strings as SQL cannot handle them.
["直行", "寸步難行"] → '["直行", "寸步難行"]'
json.dumps() turns the list into a string.
[] is specified inside the d.get() to ensure an empty list is returned if example or quote are missing instead of None.
ensure_ascii=False is usable to keep the Unicode characters and not ASCII only. So that Chinese characters don’t get converted into things like: \u76f4\u884c.
for d in het.get("definitions", []): cur.execute( "INSERT INTO definition (heteronym_id, type, def, example, quote) VALUES (?, ?, ?, ?, ?)", ( heteronym_id, d.get("type"), d.get("def"), json.dumps(d.get("example", []), ensure_ascii=False), json.dumps(d.get("quote", []), ensure_ascii=False), ), )
Finally, we can commit and close the connection:
commit() is used to save everything.
close() is used to close the connection with the database.
conn.commit()conn.close()
In Swift
Next, we need to prepare the database for use in the SwiftUI app. We create corresponding Swift structs to model our SQLite tables, following the standards of SQLite Data by Point-Free.
@Table("entry")struct Entry: Identifiable { let id: Int var title: String var radical: String @Column("stroke_count") var strokeCount: Int @Column("non_radical_stroke_count") var nonRadicalStrokeCount: Int}@Table("heteronym")struct Heteronym: Identifiable { let id: Int @Column("entry_id") var entryID: Int var pinyin: String var bopomofo: String}@Table("definition")struct Definition: Identifiable { let id: Int @Column("heteronym_id") var heteronymID: Int var type: String var def: String var example: String var quote: String}
What are @Table and @Column?
@Table is used to map the struct in Swift to the corresponding table in the database. @Column is used when the name of a property into a table in Swift and the database column don’t match.
App.swift
In the app’s entry point structure marked with @main we can define an initializer and call the prepareDependencies function:
prepareDependencies is a function used to configure global dependencies at the app’s entry point.
It takes a closure that receives a dependency container (the first parameter $0)
We use Bundle.main.path to retrieve the dictionary database file’s path and assign it to the dbPath variable. We force unwrap it here because the results of Bundle.main.path is optional as the file may not exist. But in our case, the dictionary file is crucial for the app so if it cannot be opened the app will just crash.
prepareDependencies { let dbPath = Bundle.main.path(forResource: "dictionary", ofType: "db")! let db = try DatabaseQueue(path: dbPath) $0.defaultDatabase = db // defines the default database to the container}
What is DatabaseQueue()?
By executing the following line, we are:
Creating a database connection to the file at dbPath.
Creating a Serial Dispatch Queue to ensure that all database operations happen one at a time.
It is a throwing function so it must be marked with try. It can throw an error in case of corrupted file, not existing file or insufficient permissions.
let db = try DatabaseQueue(path: dbPath)
It works like the following:
graph TD
A[prepareDependencies called] --> B[Creates container]
B --> C[Passes container as $0 to your closure]
C --> D[You modify $0.defaultDatabase]
D --> E[Container saved globally]
E --> F[Available everywhere via @Dependency]
style C fill:#f9f,stroke:#333,stroke-width:2px
style D fill:#bbf,stroke:#333,stroke-width:2px
ViewModel: Search by Stroke Count Functionality
To communicate between the UI and the database, we create a DictionaryModel class, which will serve as our ViewModel:
@Observable is a Swift macro (introduced in iOS 17+) that automatically makes all properties of this class observable. Before it, we would have to conform the model to ObservableObject and mark each of the changing properties with @Published.
Why a class?
Because all views should share the same instance.
Inside the ViewModel, we are going to declare a variable to represent the connection to the database and tell SwiftUI to ignore changes to this property as the database connection itself doesn’t need to trigger view updates:
@ObservationIgnored@Dependency(\.defaultDatabase) var database
What is @Dependency?
@Dependency is a property wrapper from the Dependencies library. It uses a key path syntax \.defaultDatabase to access the database we configured in App.swift. This is called Dependency Injection which means that we are not creating our own database connection but receiving it from outside.
graph LR
A[App.swift<br/>prepareDependencies] --> B[Sets defaultDatabase]
B --> C[Dependency Container]
C --> D[@Dependency injects it here]
D --> E[DictionaryModel uses it]
style C fill:#bbf,stroke:#333,stroke-width:2px
style D fill:#f9f,stroke:#333,stroke-width:2px
Other Properties
var entries: [Entry] = []var isLoading = falsevar errorMessage: String?
Where:
entries: Is an array of search results. When it changes, any SwiftUI view observing it will refresh.
isLoading: Tracks whether a search is currently in progress. It is used in the UI to show a loading spinner.
errorMessage: Optional string to hold error messages. It is nil when everything is fine.
Asynchronous Database Query
The searchByStrokeCount function handles the search logic. It first performs input validation using a guard statement, ensuring the strokeCount is a valid positive number:
isLoading: Sets the loading flag before starting the query. It triggers the UI thanks to @Observable that makes the view update automatically to show the ProgressView with the text "搜尋中..."
errorMessage = nil means there are no error messages.
isLoading = trueerrorMessage = nil
The database query
We start a do-catch block for error handling. Here, any throwing operation inside can be caught.
database.read opens a read-only database transaction.
This operation can cause throw an error so it is marked with try
await signalizes it is an asynchronous operation meaning that the function suspends here while waiting for the database.
db is the database connection handle.
try Entry starts building a query on the Entry table
.where adds a filter condition like SQL’s WHERE clause
Here. $0 represents an entry object.
.order is similar to SQL ORDER BY. Here, we are accessing the .\title key path to the title property.
.fetchAll actually runs the query.
We catch all possible errors and display a localized error message.
do { entries = try await database.read { db in try Entry .where { $0.strokeCount == strokeCount } .order(by: \.title) .fetchAll(db) }catch { errorMessage = "搜尋失敗: \(error.localizedDescription)"entries = []}
What fetchAll is doing here:
graph TD
A[Query Builder] --> B[Generate SQL]
B --> C[Execute on Database]
C --> D[Raw SQLite Rows]
D --> E[Map to Entry structs]
E --> F[Return Array of Entry to entries]
style E fill:#bbf,stroke:#333,stroke-width:2px
style F fill:#f9f,stroke:#333,stroke-width:2px
After finishing the query, we set isLoading to false:
isLoading = false
Visually:
sequenceDiagram
participant UI as StrokeCountSearchView
participant Model as DictionaryModel
participant SQLite as SQLiteData
participant DB as Database File
UI->>Model: searchByStrokeCount(5)
activate Model
Model->>Model: guard strokeCount > 0
Model->>Model: isLoading = true
Note over UI: Shows ProgressView
Model->>SQLite: database.read { db in ... }
activate SQLite
SQLite->>SQLite: Build query with .where and .order
SQLite->>DB: Execute SQL: SELECT * FROM entry WHERE stroke_count = 5 ORDER BY title
activate DB
DB-->>SQLite: Return rows
deactivate DB
SQLite->>SQLite: Map rows to [Entry]
SQLite-->>Model: Return [Entry]
deactivate SQLite
Model->>Model: entries = [Entry]
Model->>Model: isLoading = false
Note over UI: Hides ProgressView<br/>Shows List
deactivate Model
UI->>UI: SwiftUI auto-refreshes
Views
Let’s start with a tab view. A tab view is just an interface that appears at the bottom of most iOS apps, and it helps us to display navigation and action buttons. Here, we will start with just two simple pages: the home screen view and the search view.
A special tab designed for searching things into your app. Here, the magnifying glass icon is automatically provided.
For the home view, I just implemented a dummy view for the moment:
Let’s start building the SearchView() for searching by stroke count. Here, we are going to use a pattern of having one main view switching between different states. Let’s start by defining some @State variables:
model holds the ViewModel instance to communicate with the model/data
searchText stores what the user types in the search bar
struct SearchView: View { @State private var model = DictionaryModel() @State private var searchText = "" var body: some View { // ... }}
Inside the body, let’s add a NavigationStack:
var body: some View { NavigationStack { ... }}
Why use NavigationStack?
NavigationStack gives us the ability to navigate between different screens (as a stack of views) and also gives us the possibility to use the navigation bar at the top.
We also have to add a Group here to be able to build a conditional view:
Group { if searchText.isEmpty { EmptySearchStateView() } else if model.isLoading { LoadingStateView() } else if let error = model.errorMessage { ErrorStateView(errorMessage: error) } else if model.entries.isEmpty { NoResultsStateView(searchText: searchText) } else { SearchResultsListView(entries: model.entries) }}
What is a Group?
It is a transparent container (like a VStack) but that does not add any visual styling.
The search interface state machine
graph TD
A[SearchView] --> B{searchText empty?}
B -->|Yes| C[EmptySearchStateView]
B -->|No| D{model.isLoading?}
D -->|Yes| E[LoadingStateView]
D -->|No| F{model.errorMessage exists?}
F -->|Yes| G[ErrorStateView]
F -->|No| H{model.entries empty?}
H -->|Yes| I[NoResultsStateView]
H -->|No| J[SearchResultsListView]
State 1: No search input
if searchText.isEmpty { EmptySearchStateView()}
struct EmptySearchStateView: View { var body: some View { ContentUnavailableView( "開始搜尋", systemImage: "magnifyingglass", description: Text("輸入筆畫數以搜尋字詞") ) }}
What is ContentUnavailableView()?
A built-in view to display empty states. It displays a custom centered icon with a title and a description.
State 2: Database query in progress
else if model.isLoading { LoadingStateView()}
struct LoadingStateView: View { var body: some View { ProgressView("搜尋中...") }}
What is ProgressView()?
A built-in view for displaying a loading indicator (a spinner)
State 3: An error occurred
else if let error = model.errorMessage { ErrorStateView(errorMessage: error)}
struct ErrorStateView: View { let errorMessage: String var body: some View { ContentUnavailableView { Label("搜尋錯誤", systemImage: "exclamationmark.triangle") } description: { Text(errorMessage) } }}
State 4: Search completed but no results found
else if model.entries.isEmpty { NoResultsStateView(searchText: searchText)}
struct NoResultsStateView: View { let searchText: String var body: some View { ContentUnavailableView( "無搜尋結果", systemImage: "magnifyingglass", description: Text("找不到 \(searchText) 畫的字") ) }}
After the group containing the conditional views, we are going to chain some view modifiers.
The first one is the navigation title:
.navigationTitle("筆畫搜尋")
Then, we need to add the search bar to the navigation view. To achieve that, we need to add the searchable modifier passing the searchText with the $ syntax to create a two-way binding between the search bar text and the variable marked with @State:
.searchable(text: $searchText, prompt: "輸入筆畫數")
Then, we apply another modifier to limit the keyboard to use the numeric keyboard since we are searching by stroke count in this demo:
.keyboardType(.numberPad)
Now, we will apply the reactive logic that connects the UI to the view model:
.onChange(of: searchText): watches for changes to searchText
{ _, newValue in }: is the way of writing parameters to a closure. The first parameter (oldValue) is ignored. The second parameter (newValue) is the updated search text
Task: Creates an asynchronous context (needed for await)
if let count = Int(newValue): tries to convert the newValue (the text the user entered) to an integer and if it is successful and the value (now called count after the cast) is greater than zero, the search is triggered by await model.searchByStrokeCount(count)
Else, the results are cleared.
.onChange(of: searchText) { _, newValue in Task { if let count = Int(newValue), count > 0 { await model.searchByStrokeCount(count) } else if newValue.isEmpty { model.entries = [] model.errorMessage = nil } }}