← ICU参数指南

simple Simple Parameter

Direct Text Replacement - The Simplest Parameter Type

Overview

The simple parameter type is the most straightforward parameter type in string.fit. It performs direct text replacement using the @{paramName} syntax, with no formatting, no transformation, and no language-specific rules.

Basic Example

Content: "Hello, @{name}!"

ICU Equivalent: "Hello, {name}!"

Params:

{
  "paramName": "name",
  "type": "simple"
}

Expected Output:

The simple parameter is the default type when no type is specified. If you omit the type field, string.fit treats the parameter as simple.

JSON Structure

The JSON definition for a simple parameter is minimal:

Simple Parameter Definition

{
  "paramName": "name",
  "type": "simple"
}

Since simple is the default type, you can also write:

Minimal Definition (No type specified)

{
  "paramName": "name"
}

When to Use Simple vs Other Types

Parameter Type Use Case Example
simple Direct text replacement, no formatting User names, item names, static text
number Numbers with formatting (currency, decimals) Price with currency formatting
date Date formatting with locale support Created date with locale-aware format
plural Plural forms (zero/one/few/many/other) Item count with plural rules
select Non-numeric conditional text Gender-specific pronouns

⚠️ Use Simple for Raw Text

Use simple parameters when you need to insert pre-formatted values that already come from your application logic. Don't use simple parameters if you need the parameter to be formatted by string.fit - use the appropriate type instead.

How Simple Parameters Work

Placeholder Syntax

In the content string, simple parameters use the @{paramName} syntax:

Content with Simple Parameter

{
  "content": "Welcome, @{username}! Your order #@{orderId} is ready."
}

When rendered with { username: "Li Ming", orderId: 12345 }, the output becomes:

"Welcome, Li Ming! Your order #12345 is ready."

Value Insertion Process

The simple parameter performs these steps:

  1. Locate the placeholder @{paramName} in the content string
  2. Retrieve the value from the provided parameters object
  3. Convert the value to string (if not already)
  4. Replace the placeholder with the string value directly

✅ No Transformation

The value is inserted exactly as provided. If the value is already formatted by your application (e.g., a localized date string), it will be inserted as-is without additional processing.

Generated Code Implementation

TypeScript/JavaScript Implementation

Simple parameters in generated code are the most straightforward - they just return the value directly:

function formatSimple(value: string): string {
    return value;
}

Swift Implementation

static func formatSimple(_ value: String) -> String {
    return value
}

Python Implementation

Python does not have a separate format_simple function because simple parameters return the value directly in format_with_params without any transformation.

Java Implementation

private static String formatSimple(String value) {
    return value;
}

✅ No Transformation Needed

The simple parameter type is the most basic type - it simply returns the value as-is. No formatting, no conversion, no special handling. The value is inserted directly into the template.

How Other Parameters Use Simple Internally

All other parameter types wrap simple parameters internally. When rendering complex types, the final text output for each branch is produced by a simple parameter mechanism:

Plural Parameter Internals

{
  "content": "You have @{count} @{itemCount}",
  "params": [
    {
      "paramName": "count",
      "type": "simple"
    },
    {
      "paramName": "itemCount",
      "type": "plural",
      "options": { "type": "cardinal" },
      "list": [
        { "value": "one", "text": "item" },
        { "value": "other", "text": "items" }
      ]
    }
  ]
}

In this plural parameter, each text field (like "item") is inserted based on the plural rule that matches the count value. The simple count parameter provides the raw number.

Select Parameter Internals

{
  "content": "@{genderText}",
  "params": [
    {
      "paramName": "genderText",
      "type": "select",
      "options": { "type": "gender" },
      "list": [
        { "value": "male", "text": "He is online" },
        { "value": "female", "text": "She is online" },
        { "value": "other", "text": "They are online" }
      ]
    }
  ]
}

Each selected text ("He is online", etc.) is rendered via the simple parameter mechanism - no transformation, just direct string insertion.

Best Practices

✅ Do: Use Simple for Pre-Formatted Values

When your application already handles formatting (e.g.,你已经本地化的日期字符串, 已格式化的货币), use simple parameters to insert them without re-formatting:

{
  "content": "Order placed on @{orderDate} for amount @{orderAmount}",
  "params": [
    { "paramName": "orderDate", "type": "simple" },
    { "paramName": "orderAmount", "type": "simple" }
  ]
}

✅ Do: Omit Type for Simple Parameters

Since simple is the default type, you can omit the type field to keep your parameter definitions clean:

{
  "paramName": "username"
}

❌ Don't: Use Simple When You Need Formatting

If you need locale-aware date formatting, proper number formatting, or grammatical plural forms, use the appropriate parameter type instead of simple:

{ "paramName": "amount", "type": "number", "options": { "style": "currency", "currency": "USD" } }
{ "paramName": "createdAt", "type": "date", "options": { "format": "yyyy-MM-dd", "zoneId": "UTC" } }
{ "paramName": "count", "type": "plural", "options": { "type": "cardinal" }, "list": [...] }

❌ Don't: Put Unformatted Numbers in Simple Parameters

If you need numbers to be formatted (e.g., currency, percentage), don't use simple. Pass pre-formatted strings or use the number type:

❌ Bad: "Price: @{price}" → "Price: 1234.56"

✅ Good: "Price: @{price}" with { "paramName": "price", "type": "number", "options": { "style": "currency", "currency": "USD" } }

Complete Import Example

Multi-Language with Simple Parameters

{
  "strings": [
    {
      "key": "greeting",
      "translations": {
        "en-US": {
          "content": "Hello, @{name}! Welcome to @{appName}.",
          "params": [
            { "paramName": "name" },
            { "paramName": "appName" }
          ]
        },
        "zh-CN": {
          "content": "你好，@{name}！欢迎来到@{appName}。",
          "params": [
            { "paramName": "name" },
            { "paramName": "appName" }
          ]
        },
        "ja-JP": {
          "content": "こんにちは、@{name}！@{appName}へようこそ。",
          "params": [
            { "paramName": "name" },
            { "paramName": "appName" }
          ]
        }
      }
    }
  ]
}