Skip to content

⭐️⭐️◽️ Add "Reason to use" and "Challenges" sections to the app modal #140

@vinybrun

Description

@vinybrun

Description: The app modal currently shows the long description, features, protocols, alternatives, and links. We want to help readers make better decisions by adding two new sections per app: Reason to use (why someone would pick this app) and Challenges (the real friction of using or self-hosting it — RAM, moderation overhead, learning curve, etc.). Both sections must be available in every language the project supports (currently pt, en, es).

What to do:

  • Update the App type (src/types/) to add the two new fields, following the existing description / longDescription / features pattern:
    • reasonToUse: single string
    • challenges: string array (use the same numbered i18n convention as features.1/2/3)
  • Update src/data/apps.ts so every app references the new i18n keys (e.g. i18n.global.t('apps.{slug}.reasonToUse') and [i18n.global.t('apps.{slug}.challenges.1'), ...2, ...3])
  • Update src/components/AppModal.vue to render the two new sections right after the existing features <ul>:
    • Match the heading style used by the protocols/alternatives blocks
    • Use the same bulleted list style as features for challenges
    • Both sections must be conditional (v-if) so they are hidden when empty — no orphaned headings
  • Add the section headings to the appModal namespace in src/locales/{pt,en,es}.json (reasonToUse, challenges)
  • Populate data for every app under apps.{slug} in all three locale files:
    • reasonToUse: 1–2 specific sentences (avoid generic "it's open source" filler)
    • challenges.1/2/3: three real friction points (e.g. hardware requirements, federation/moderation overhead, install complexity, ongoing maintenance cost)
    • Keep tone and length consistent with existing longDescription and features entries
  • Use AI to gather the data — but review before submitting. Researching 56 apps by hand is tedious, but AI hallucinates self-hosting specifics (wrong RAM numbers, outdated install paths, features that don't exist). Spot-check anything that sounds suspiciously specific against the project's docs.
  • Testing checklist before opening the PR:
    • Loads correctly on desktop — sections appear in the right order, long content wraps properly, no layout break
    • Loads correctly on mobile — readable card sizes, no horizontal scroll, headings/bullets sized appropriately
    • Switch language with the language switcher and confirm both sections update across pt, en, es
    • Open an app with intentionally empty reasonToUse or challenges and confirm the section is hidden (not an empty heading)
    • Spot-check a couple of long entries to confirm spacing still feels right

Suggested workflow: clone the repo, run [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) in the project root, and paste this prompt:

/plan

I'm working on Sovereinia/guia (Vue 3 + TypeScript + Tailwind + DaisyUI + vue-i18n).
Goal: add two new sections — "Reason to use" and "Challenges" — to the app modal,
populated for every app in all 3 supported languages (pt, en, es).

Please do the following:

1. Read `src/types/` and update the `App` type to add:
   - `reasonToUse`: string
   - `challenges`: string[]
   Follow the same pattern used by `description`, `longDescription`, `features`.

2. Update `src/data/apps.ts` so every app references the new i18n keys:
   - `i18n.global.t('apps.{slug}.reasonToUse')`
   - `[i18n.global.t('apps.{slug}.challenges.1'), ..2, ..3]` (matching the
     numbered `features.1/2/3` convention).

3. Update `src/components/AppModal.vue` to render the two new sections right
   after the existing `features` <ul>. Use the same heading style as
   protocols/alternatives, and the same bulleted list style as features.
   Each section must be conditional (`v-if`) so it stays hidden when empty.
   Add the section headings to the `appModal` namespace in all three locale
   files (`reasonToUse`, `challenges`).

4. For EVERY app under `apps.{slug}` in `src/locales/pt.json`, `en.json`, and
   `es.json`, add:
   - `reasonToUse`: 1–2 specific sentences (no generic filler)
   - `challenges.1/2/3`: three real friction points (hardware needs, federation
     /moderation overhead, install complexity, ongoing maintenance, learning
     curve, ActivityPub interop quirks, etc.)
   Match the tone and length of the existing `longDescription` / `features`.
   Research each app briefly first — don't fabricate hardware specs or features.
   The list of apps lives in the keys of the `apps` object in any locale file.

5. Run `npm run dev` and verify the modal renders for at least 5 different apps
   across all 3 languages, plus a mobile viewport (~375px wide).

Show me the final diff for review before committing — I want to spot-check the
content, especially `challenges`, since AI often gets self-hosting specifics
wrong and I'd rather catch hallucinations now than ship them.

Helpful tips:

  • App data lives in src/data/apps.ts; translation keys for each app live under apps.{slug} in src/locales/{pt,en,es}.json — follow the existing structure exactly (note that features and links use numbered keys 1/2/3, not arrays)
  • The App type is the source of truth — once you update it, TypeScript will flag any missing field in apps.ts
  • The modal component is src/components/AppModal.vue; the existing features list around the <ul v-if="localApp.features?.length"> block is the right reference for the new challenges section
  • Don't ship AI output unreviewed — self-hosting requirements drift fast, and inaccurate guidance is worse than no guidance
  • Discuss any structural questions on our [Hackathon's Discord channel](https://discordapp.com/channels/1365364448461721611/1376586127443623976)

Good first issue? Yes
Type: Feature / Content
Task Labels: enhancement, i18n, content, good first issue
Difficulty: ⭐️⭐️◽️

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions