diff options
| -rw-r--r-- | _layouts/page.html | 1 | ||||
| -rw-r--r-- | _posts/2014-07-03-our-research-into-the-impact-of-technologies-on-foi.md | 218 | ||||
| -rw-r--r-- | docs/customising/translation.md | 107 | ||||
| -rw-r--r-- | docs/developers/i18n.md | 161 | ||||
| -rw-r--r-- | docs/glossary.md | 86 | ||||
| -rw-r--r-- | docs/installing/macos.md | 32 | ||||
| -rw-r--r-- | docs/installing/manual_install.md | 47 | ||||
| -rw-r--r-- | docs/running/admin_manual.md | 19 | ||||
| -rw-r--r-- | docs/running/upgrading.md | 54 |
9 files changed, 635 insertions, 90 deletions
diff --git a/_layouts/page.html b/_layouts/page.html index 9d8925f07..f1faa3950 100644 --- a/_layouts/page.html +++ b/_layouts/page.html @@ -71,6 +71,7 @@ layout: default <ul> <li><a href="{{ site.baseurl }}docs/developers/overview/">High-level overview</a></li> <li><a href="{{ site.baseurl }}docs/developers/directory_structure/">Directory structure</a></li> + <li><a href="{{ site.baseurl }}docs/developers/i18n/">Internationalisation</a></li> <li><a href="{{ site.baseurl }}docs/developers/api/">API</a></li> </ul> </li> diff --git a/_posts/2014-07-03-our-research-into-the-impact-of-technologies-on-foi.md b/_posts/2014-07-03-our-research-into-the-impact-of-technologies-on-foi.md new file mode 100644 index 000000000..d9fb7e403 --- /dev/null +++ b/_posts/2014-07-03-our-research-into-the-impact-of-technologies-on-foi.md @@ -0,0 +1,218 @@ +--- +author: Tom Longley and Savita Bailur +comments: true +date: 2014-07-03 14:54:07+00:00 +layout: post +slug: 'our-research-into-the-impact-of-technologies-on-foi' +title: Our research into the impact of technologies on FOI +wordpress_id: 455 +--- +In March this year mySociety put out [a call for a research consultant](https://www.mysociety.org/2014/03/31/seeking-a-research-contractor-with-transparency-and-accountability-expertise/) to look at the place that Alaveteli - mySociety's open source freedom of information (FOI) filer - might have in creating cultures of transparency and accountability. So, eventually, mySociety chose us - Savita Bailur and Tom Longley. Since we're the strangers here, we'd like to introduce ourselves, give you an idea of the approach that we'll be taking, and what we've found in the first weeks of the research. + +##Who are we? + +Savita is a consultant who has previously worked for the World Bank, Commonwealth Secretariat, USAID, and Panos and taught at the University of Manchester and London School of Economics. She has a personal interest in freedom of information as her family in India successfully used the Right to Information Act in India to find out about violations of building regulations (although the legal process to change things is taking more time). If there's one thing of Savita's to read, it's [Closing the Feedback Loop : Can Technology Bridge the Accountability Gap?](https://openknowledge.worldbank.org/handle/10986/18408), which she wrote in and co-edited. + +Tom is a human rights and technology consultant who's worked on field investigations of crimes against humanity. After years wading through stacks of documentation and interview transcripts, he became interested in how data and technologies could help this work. He has since worked for investigation organisations in Kosovo, Sierra Leone, Bangladesh, Cambodia, Zimbabwe and others helping building up their ability to use data and technologies safely and effectively. Tom also consults for Tactical Technology Collective, Global Witness and Open Society Foundations. If there's one thing of his to read, it's probably ["Deadly Environment"](http://globalwitness.org/deadlyenvironment), a report about murders of environmental defenders. + +##What are we doing? + +The top level question we're addressing is: "In what circumstances, if any, can tools like Alaveteli be shown to have measurable impacts on the ability of citizens to exert power over underperforming institutions?" To get at this, we'll be doing three things: + +* First, a review of the studies so far on the impact of the internet on FOI. Our early findings flag a lot of research into the mechanics of FOI, but very little on its impact, other than anecdotal evidence. There are some great points and questions raised in the literature however, which we combine into roughly ten areas of impact. These include FOI's role in aiding the transition from transparency to accountability, the role of different groups (like the media, movements, non-governmental and community groups), public and institutional perceptions, security and privacy. We find that the overall challenge is that the technology is only part of the FOI value chain - governments also need to respond, and sanctions/enforcements put in place which ensure governments are transparent and accountable. + +* Second, a field scan of practitioners. There are nearly 20 FOI websites running Alaveteli. Some sites are just getting started, like [Доступ До Правди ("Access the Truth")](https://dostup.pravda.com.ua/list/all) in Ukraine. By talking with the people setting up and using these sites, we aim to pull together a view of what makes a successful implementation, what the challenges are, and what can be learned for future implementors of FOI sites. + +* Third, a list of critical success factors, pulled together from both the literature and practitioner reviews, which will be translated into major languages. + +All these documents should be published this September, along with something brief and readable with the topline findings. + + +##What are we asking of you? + +If you run an Alaveteli site, we may have already emailed you or will do very soon asking if you can spare some time to talk with us as part of the practioner review. More generally, we're continuing to look for more articles and 'grey' literature, in particular any quantitative studies, about the role of technologies in FOI. We have a shorter list of articles we have found so far [here](#short-reference-list), and a longer list [here](#long-reference-list) - have we missed any? Please let us know. + +To wrap up, this is first generation research into this area. We hope to have material that can be useful to you and mySociety. Any questions, get in touch via the comments field, or via twitter at any of our handles ([@alaveteli_foi](https://twitter.com/alaveteli_foi), [@tlongers](https://twitter.com/tlongers), [@savitabailur](https://twitter.com/savitabailur)). + +##Short reference list + +Baisakh, Pradeep. 2007. “India Together: Villagers Push for Work Benefits in Orissa.” <http://indiatogether.org/egarti-human-rights>. + +Bauhr, Monika, and Marcia Grimes. 2014. “Indignation or Resignation: The Implications of Transparency for Societal Accountability.” Governance 27 (2): 291–320. doi:10.1111/gove.12033. + +Bertot, John C., Paul T. Jaeger, and Justin M. Grimes. 2010. “Using ICTs to Create a Culture of Transparency: E-Government and Social Media as Openness and Anti-Corruption Tools for Societies.” Government Information Quarterly 27 (3): 264–71. doi:10.1016/j.giq.2010.03.001. + +Birkinshaw, Patrick. 2010. “Freedom of Information and Its Impact in the United Kingdom.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 312–21. doi:10.1016/j.giq.2010.06.006. + +Brooke, Heather. 2011. “Fess up - or Face a Future of Leaks.” British Journalism Review 22 (1): 17–19. doi:10.1177/09564748110220010601. + +Cabo, David. (2012). “Tu derecho a saber” David Cabo at TedxMadrid. Accessed June 25. <http://www.youtube.com/watch?v=Okta1VjTM0I>. + +Cherry, Morag, and David McMenemy. 2013. “Freedom of Information and ‘vexatious’ Requests — The Case of Scottish Local Government.” Government Information Quarterly 30 (3): 257–66. doi:10.1016/j.giq.2013.02.004. + +Consumer Unity and Trust Society. 2010. Analysing the Right to Information Act in India. Jaipur: Consumer Unity and Trust Society. + +Costa, Samia. 2013. “Do Freedom of Information Laws Decrease Corruption?” Journal of Law, Economics, and Organization 29 (6): 1317–43. doi:10.1093/jleo/ews016. + +Dunion, K. 2011. “Viewpoint: In Defence of Freedom of Information.” Information Polity 16 (2): 93–96. doi:10.3233/IP-2011-0233. + +Etzioni, Amitai. 2010. “Is Transparency the Best Disinfectant?” Journal of Political Philosophy 18 (4): 389–404. doi:10.1111/j.1467-9760.2010.00366.x. + +Finel, Bernard I., and Kristin M. Lord. 1999. “The Surprising Logic of Transparency.” International Studies Quarterly 43 (2): 325–39. doi:10.1111/0020-8833.00122. + +Fox, Jonathan. 2007. “The Uncertain Relationship between Transparency and Accountability.” Development in Practice 17 (4-5): 663–71. doi:10.1080/09614520701469955. + +Gandhi, Shailesh. 2007. “The RTI Movement Will Lead India to Swaraj.” Accessed June 24. <http://www.rediff.com/news/2007/oct/11guest.htm>. +Global Right to Information Rating. 2014. “Country Data.” <http://www.rti-rating.org/>. + +Government of India. 2005. “Right to Information, Planning Commission, Governement of India.” <http://planningcommission.gov.in/rti/index.php>. + +Grimmelikhuijsen, Stephan. 2012. “A Good Man but a Bad Wizard. About the Limits and Future of Transparency of Democratic Governments.” Information Polity 17 (3): 293–302. doi:10.3233/IP-2012-000288. + +Hazell, R., Benjamin Worthy, and M. Glover. 2010. The Impact of the Freedom of Information Act on Central Government in the UK: Does Freedom of Information Work? London: Palgrave Macmillan. <http://www.palgrave.com/products/title.aspx?pid=407804>. + +Hazell, Robert, and Ben Worthy. 2010. “Assessing the Performance of Freedom of Information.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 352–59. doi:10.1016/j.giq.2010.03.005. + +India Together: RTI: An Enormous Power with the People: Vinita Deshmukh - 07 August 2006. 2006. <http://indiatogether.org/arvind-interviews>. + +Jaeger, Paul T., and John Carlo Bertot. 2010. “Transparency and Technological Change: Ensuring Equal and Sustained Public Access to Government Information.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 371–76. doi:10.1016/j.giq.2010.05.003. + +Joshi, Anuradha. 2013. “Do They Work? Assessing the Impact of Transparency and Accountability Initiatives in Service Delivery.” Development Policy Review 31: s29–s48. doi:10.1111/dpr.12018. + +McDonagh, Maeve. 2013. “The Right to Information in International Human Rights Law.” Human Rights Law Review 13 (1). <http://papers.ssrn.com/abstract=2446424>. + +Meijer, Albert Jacob. 2003. “Transparent Government: Parliamentary and Legal Accountability in an Information Age.” Information Polity 8 (1): 67–78. + +Michener, Greg. 2011. “FOI Laws Around the World.” Journal of Democracy 22 (2): 145–59. doi:10.1353/jod.2011.0021. + +Michener, Greg, and Katherine Bersch. 2013. “Identifying Transparency.” Information Polity 18 (3): 233–42. doi:10.3233/IP-130299. + +Minihan, Mary. 2014. “Cabinet Abolishes €15 Freedom of Information Fee”, July 1. <http://www.irishtimes.com/news/politics/cabinet-abolishes-15-freedom-of-information-fee-1.1851481>. + +Nye, Joseph S., Philip Zelikow, and David C. King. 1997. Why People Don’t Trust Government. Boston: Harvard University Press. + +Roberts, Alasdair. 2010. “A Great and Revolutionary Law? The First Four Years of India’s Right to Information Act.” Public Administration Review 70 (6): 925–33. doi:10.1111/j.1540-6210.2010.02224.x. + +Shepherd, Elizabeth, Alice Stevenson, and Andrew Flinn. 2011. “Freedom of Information and Records Management in Local Government: Help or Hindrance?” Information Polity 16 (2): 111–21. doi:10.3233/IP-2011-0229. + +Spence, Kate, and William Dinan. 2011. “Healthy Tensions? Assessing FOI Uptake in the Voluntary Sector in Scotland.” Information Polity 16 (2): 97–109. doi:10.3233/IP-2011-0228. + +Srivastava, Smita. 2010. “The Right to Information in India: Implementation and Impact.” Afro Asian Journal of Social Sciences 1 (1): 1–18. + +Tuderechoasaber.es (2012). Informe Tuderechoasaber.es 2012. Accessed June 25. <http://blog-tdas.s3.amazonaws.com/blog-tdas/2013/04/informe2012.pdf> + +Tuderechoasaber.es (2013). Silencio masivo de las instituciones en el año de la transparencia: Informe Tuderechoasaber.es 2013. Accessed June 25. <http://blog.tuderechoasaber.es/informe2013/>. + +UNDP. 2006. A Guide to Measuring the Impact of Right to Information Programmes; Practical Guide Note. New York: UNDP. + +Worthy, Ben. 2010. “More Open but Not More Trusted? The Effect of the Freedom of Information Act 2000 on the United Kingdom Central Government.” Governance 23 (4): 561–82. doi:10.1111/j.1468-0491.2010.01498.x. + + +##Long reference list + +Baisakh, Pradeep. 2007. “India Together: Villagers Push for Work Benefits in Orissa.” <http://indiatogether.org/egarti-human-rights>. + +Bannister, Frank, and Regina Connolly. 2011. “The Trouble with Transparency: A Critical Review of Openness in E-Government.” Policy & Internet 3 (1): 1–30. doi:10.2202/1944-2866.1076. + +Bauhr, Monika, and Marcia Grimes. 2014. “Indignation or Resignation: The Implications of Transparency for Societal Accountability.” Governance 27 (2): 291–320. doi:10.1111/gove.12033. + +Bentham, Jeremy, and Sir John Bowring. 1839. Works of Jeremy Bentham. W. Tait. + +Berliner, Daniel. 2014. “The Political Origins of Transparency.” The Journal of Politics 76 (02): 479–91. doi:10.1017/S0022381613001412. + +Bertot, John C., Paul T. Jaeger, and Justin M. Grimes. 2010. “Using ICTs to Create a Culture of Transparency: E-Government and Social Media as Openness and Anti-Corruption Tools for Societies.” Government Information Quarterly 27 (3): 264–71. doi:10.1016/j.giq.2010.03.001. + +Birkinshaw, Patrick. 2010. “Freedom of Information and Its Impact in the United Kingdom.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 312–21. doi:10.1016/j.giq.2010.06.006. + +Breton, Albert. 2007. The Economics of Transparency in Politics. Aldershot: Ashgate Publishing, Ltd. + +Brooke, Heather. 2011. “Fess up - or Face a Future of Leaks.” British Journalism Review 22 (1): 17–19. doi:10.1177/09564748110220010601. + +Cabo, David. (2012). “Tu derecho a saber” David Cabo at TedxMadrid. Accessed June 25. <http://www.youtube.com/watch?v=Okta1VjTM0I>. + +Cherry, Morag, and David McMenemy. 2013. “Freedom of Information and ‘vexatious’ Requests — The Case of Scottish Local Government.” Government Information Quarterly 30 (3): 257–66. doi:10.1016/j.giq.2013.02.004. + +Consumer Unity and Trust Society. 2010. Analysing the Right to Information Act in India. Jaipur: Consumer Unity and Trust Society. + +Costa, Samia. 2013. “Do Freedom of Information Laws Decrease Corruption?” Journal of Law, Economics, and Organization 29 (6): 1317–43. doi:10.1093/jleo/ews016. + +Douglass, Frederick. 2014. “(1857) Frederick Douglass, ‘If There Is No Struggle, There Is No Progress’ - The Black Past: Remembered and Reclaimed.” Accessed June 24. <http://www.blackpast.org/1857-frederick-douglass-if-there-no-struggle-there-no-progress>. + +Dunion, K. 2011. “Viewpoint: In Defence of Freedom of Information.” Information Polity 16 (2): 93–96. doi:10.3233/IP-2011-0233. + +Etzioni, Amitai. 2010. “Is Transparency the Best Disinfectant?” Journal of Political Philosophy 18 (4): 389–404. doi:10.1111/j.1467-9760.2010.00366.x. + +Fenster, Mark. 2010. Seeing the State: Transparency as Metaphor. SSRN Scholarly Paper ID 1562762. Gainesville, Florida: University of Florida. <http://papers.ssrn.com/abstract=1562762>. + +Finel, Bernard I., and Kristin M. Lord. 1999. “The Surprising Logic of Transparency.” International Studies Quarterly 43 (2): 325–39. doi:10.1111/0020-8833.00122. + +Fox, Jonathan. 2007. “The Uncertain Relationship between Transparency and Accountability.” Development in Practice 17 (4-5): 663–71. doi:10.1080/09614520701469955. + +Fung, Archon. 2006. “Varieties of Participation in Complex Governance.” Public Administration Review 66: 66–75. doi:10.1111/j.1540-6210.2006.00667.x. + +Gandhi, Shailesh. 2007. “The RTI Movement Will Lead India to Swaraj.” +Global Right to Information Rating. 2014. “Country Data.” <http://www.rti-rating.org/>. + +Government of India. 2005. “Right to Information, Planning Commission, Governement of India.” <http://planningcommission.gov.in/rti/index.php>. + +Grimmelikhuijsen, Stephan. 2012. “A Good Man but a Bad Wizard. About the Limits and Future of Transparency of Democratic Governments.” Information Polity 17 (3): 293–302. doi:10.3233/IP-2012-000288. + +Hazell, R., Benjamin Worthy, and M. Glover. 2010. The Impact of the Freedom of Information Act on Central Government in the UK: Does Freedom of Information Work? London: Palgrave Macmillan. <http://www.palgrave.com/products/title.aspx?pid=407804>. + +Hazell, Robert, and Ben Worthy. 2010. “Assessing the Performance of Freedom of Information.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 352–59. doi:10.1016/j.giq.2010.03.005. + +Hood, Christopher. 2006. “Transparency in Historical Perspective.” In Transparency: The Key to Better Governance?, edited by Christopher Hood and David Heald, 3–23. Oxford, UK: Oxford University Press. <http://www.oup.co.uk/>. + +India Together: RTI: An Enormous Power with the People: Vinita Deshmukh - 07 August 2006. 2006. <http://indiatogether.org/arvind-interviews>. + +Jaeger, Paul T., and John Carlo Bertot. 2010. “Transparency and Technological Change: Ensuring Equal and Sustained Public Access to Government Information.” Government Information Quarterly, Special Issue: Open/Transparent Government, 27 (4): 371–76. doi:10.1016/j.giq.2010.05.003. + +Joshi, Anuradha. 2013. “Do They Work? Assessing the Impact of Transparency and Accountability Initiatives in Service Delivery.” Development Policy Review 31: s29–s48. doi:10.1111/dpr.12018. + +Lathrop, Daniel, and Laurel Ruma. 2010. Open Government: Collaboration, Transparency, and Participation in Practice. Sebastopol, CA: O’Reilly Media, Inc. + +Linders, Dennis. 2012. “From E-Government to We-Government: Defining a Typology for Citizen Coproduction in the Age of Social Media.” Government Information Quarterly, Social Media in Government - Selections from the 12th Annual International Conference on Digital Government Research (dg.o2011), 29 (4): 446–54. doi:10.1016/j.giq.2012.06.003. + +McDonagh, Maeve. 2013. “The Right to Information in International Human Rights Law.” Human Rights Law Review 13 (1). <http://papers.ssrn.com/abstract=2446424>. + +Meijer, Albert J. 2012. “Introduction to the Special Issue on Government Transparency.” International Review of Administrative Sciences 78 (1): 3–9. doi:10.1177/0020852311435639. + +Meijer, Albert Jacob. 2003. “Transparent Government: Parliamentary and Legal Accountability in an Information Age.” Information Polity 8 (1): 67–78. + +Michener, Greg. 2011. “FOI Laws Around the World.” Journal of Democracy 22 (2): 145–59. doi:10.1353/jod.2011.0021. + +Michener, Greg, and Katherine Bersch. 2013. “Identifying Transparency.” Information Polity 18 (3): 233–42. doi:10.3233/IP-130299. + +Minihan, Mary. 2014. “Cabinet Abolishes €15 Freedom of Information Fee”, July 1. <http://www.irishtimes.com/news/politics/cabinet-abolishes-15-freedom-of-information-fee-1.1851481>. + +Nye, Joseph S., Philip Zelikow, and David C. King. 1997. Why People Don’t Trust Government. Boston: Harvard University Press. + +Official Information: Your Right To Know — Ministry of Justice, New Zealand. 2014. Accessed June 24. <http://www.justice.govt.nz/publications/global-publications/o/official-information-your-right-to-know>. + +OneWorld. 2011. ICT Facilitated Access to Information Innovations. + +Press Association. 2009. “Telegraph Reveals Cost of MP’s Expense Story.” + +Roberts, Alasdair. 2010. “A Great and Revolutionary Law? The First Four Years of India’s Right to Information Act.” Public Administration Review 70 (6): 925–33. doi:10.1111/j.1540-6210.2010.02224.x. + +Schedler, Andreas. 1999. “Conceptualizing Accountability.” In The Self-Restraining State: Power and Accountability in New Democracies, edited by Larry Diamond and Marc Plattner, 13–28. London: Lynne Rienner Publishers. + +Shepherd, Elizabeth, Alice Stevenson, and Andrew Flinn. 2011. “Freedom of Information and Records Management in Local Government: Help or Hindrance?” Information Polity 16 (2): 111–21. doi:10.3233/IP-2011-0229. + +Smith, Matthew L., and Katherine M. A. Reilly. 2014. Open Development: Networked Innovations in International Development. Ottawa: MIT Press. + +Spence, Kate, and William Dinan. 2011. “Healthy Tensions? Assessing FOI Uptake in the Voluntary Sector in Scotland.” Information Polity 16 (2): 97–109. doi:10.3233/IP-2011-0228. + +Srivastava, Smita. 2010. “The Right to Information in India: Implementation and Impact.” Afro Asian Journal of Social Sciences 1 (1): 1–18. + +Tuderechoasaber.es (2012). Informe Tuderechoasaber.es 2012. Accessed June 25. <http://blog-tdas.s3.amazonaws.com/blog-tdas/2013/04/informe2012.pdf> + +Tuderechoasaber.es (2013). Silencio masivo de las instituciones en el año de la transparencia: Informe Tuderechoasaber.es 2013. Accessed June 25. <http://blog.tuderechoasaber.es/informe2013/>. + +UNDP. 2006. A Guide to Measuring the Impact of Right to Information Programmes; Practical Guide Note. New York: UNDP. + +Wilson, Woodrow, and William Bayard Hale. 1918. The New Freedom: A Call for the Emancipation of the Generous Energies of a People. Doubleday, Page. + +Worthy, Ben. 2010. “More Open but Not More Trusted? The Effect of the Freedom of Information Act 2000 on the United Kingdom Central Government.” Governance 23 (4): 561–82. doi:10.1111/j.1468-0491.2010.01498.x. + +Xiao, Weibing. 2010. “The Improved Information Environment as a Key Rationale for Freedom of Information Reform in China.” Information Polity 15 (3): 177–87. doi:10.3233/IP-2010-0214. diff --git a/docs/customising/translation.md b/docs/customising/translation.md index bcf6514e5..d4ccedfa7 100644 --- a/docs/customising/translation.md +++ b/docs/customising/translation.md @@ -12,38 +12,85 @@ title: Translation it. This page explains how. </p> +## Alaveteli already contains translations! + +Alaveteli ships ready to run in a number of different languages. +If Alaveteli has already been translated into the language (or languages) you +need, you just need to configure it -- see +[`AVAILABLE_LOCALES`]({{ site.baseurl }}docs/customising/config/#available_locales). + +[Look in the `locale/` directory](https://github.com/mysociety/alaveteli/tree/master/locale) +to see what translations are already available. Some are complete +translations of the site. Others are only partial -- either because the translations +have not been finished yet, or else because the translators have not updated the +texts since developers changed or added text on the site. + +There are two reasons the translations may need more work before you can use them: + +* **the language you want is not one of those we already have** <br> In this + case, there will be no entry in ``locale/`` for it, because nobody has yet + translated Alaveteli into your language. See the rest of this page to learn + how to add a new translation. + +* **the translation for your language is incomplete, or lagging behind** <br> + This might simply be because it is a work in progress. Furthermore, sometimes + an incomplete translation already covers all the areas of the site you need + anyway. Of course, you can add to a partial translation, but it's a good idea + to check with us first, since we'll probably know who is working on the + current translation and what state it's in. + +Translators are members of the Alaveteli +[community]({{site.baseurl}}community/), and often work separately from the +developers. This means translations can lag a little behind the code. However, +our release process includes a "translation freeze", which gives the +translators a chance to catch up -- read the rest of this page for details. + ## Alaveteli's translations -The software translations are implemented using GNU gettext, and the resource -files are managed in Transifex. +You don't need to be a programmer to translate Alaveteli -- we use an external +website called Transifex to help manage translations. This makes it easy for +translators to get to work, but it does mean you (or your technical team) +need to do a little extra work to get those translations back into Alaveteli +when they are ready. The Transifex project is at -[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) -- you'll probably want an account there (ask on the mailing -list). It has a fairly easy-to-use interface for contributing translations. +[https://www.transifex.net/projects/p/alaveteli](https://www.transifex.net/projects/p/alaveteli) +-- you'll probably want an account there (ask on the mailing list). It has a +fairly easy-to-use interface for contributing translations. + +Alaveteli localises strings using GNU gettext and +<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> & <code>.po</code> files</a>. +If you're a developer, you should read +[internationalising Alaveteli]({{ site.baseurl }}docs/developers/i18n/). -There are three roles in the translation process, and each one is described -below: **translator**, **developer**, and **release manager**. You probably only -need to know about the one that applies to you. -## Translation process: translator's view +## What a translator needs to do **If you're just working on translating Alaveteli into a language you know, then this section is for you.** +> Remember that Alaveteli +> [already comes with some translations](#alaveteli-already-contains-translations), +> so check first that you really need to do this. Maybe someone has already +> translated Alaveteli into the language you need! + When a developer adds a new feature to the user interface in Alaveteli, they use some code to mark sentences or words ("strings") that they think will need to be translated. -When the Alaveteli release manager is planning a release, they will upload a -template containing all the strings to be translated (called a POT) to -Transifex. This causes your own translations in Transifex to be updated with +When the Alaveteli +<a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release manager</a> +is planning a release, they will upload a +template containing all the strings to be translated (called a +<a href="{{site.baseurl}}docs/glossary/#po" class="glossary__link"><code>.pot</code> file</a>) +to Transifex. This causes your own translations in Transifex to be updated with the latest strings. When you visit Transifex, it will prompt you to fill out values for all new strings, and all strings that have been modified. In the case where a string has only been slightly modified, such as with punctuation ("Hello" has become "Hello!"), Transifex will suggest a suitable translation for you (look for the -"suggestions" tab under the source string). +*Suggestions* tab under the source string). In order for this feature to work properly, the release manager has to download your translations, run a program that inserts the suggestions, and then upload @@ -59,11 +106,12 @@ The release manager will also give you a **translation deadline**. After this date, you can continue to contribute new translations, but they won't make it into the release. + ### General notes on translation in Transifex Some strings will have comments attached to them from the Alaveteli application developers about the context in which the text appears in the -application — these comments will appear under the 'Details' tab for the text +application — these comments will appear under the *Details* tab for the text in Transifex. Some strings will have **placeholders** in them to indicate that Alaveteli @@ -104,19 +152,24 @@ they do not appear on the site anywhere at the moment, and when they do, they will only be used in the admin interface. If you do translate them, only translate the text that comes *after* the `|`. -## Translation process: developers' view -**If you're writing new code for Alaveteli, then you're a developer, and you +## How the translations get into Alaveteli + +In order to get the translated strings from Transifex into Alaveteli, follow +the instructions in these [deployment notes]({{ site.baseurl }}docs/developers/i18n/#deployment-notes). +This will be the job of the technical people on your team (or +even mySociety's release manager). If translators aren't technical, they can +use Transifex without needing to worry about this. + + +## Developers and internationalisation + +If you're writing new code for Alaveteli, then you're a developer, and you need to understand how to make any text you add easy for translators to work -with.** - -Please read our [internationalisation -guide](http://mysociety.github.io/internationalization.html) for our advice on -using strings that will need translation. This applies across all mySociety -projects, not just Alaveteli. - -The release manager will enforce a translation freeze just before a new release -is cut. During such time, you must not introduce new strings to the code if -your work is due for inclusion in this release. This is necessary to allow -translators time to complete and check their translations against all the known -strings. +with -- see the page about +[internationalising Alaveteli]({{site.baseurl}}docs/developers/i18n/). + +If you are a developer or translator actively working on internationalising +Alaveteli code, you should talk to us to find out when the next release is due, +so your translations can be prepared in time to be included in it. + diff --git a/docs/developers/i18n.md b/docs/developers/i18n.md new file mode 100644 index 000000000..deabc99a1 --- /dev/null +++ b/docs/developers/i18n.md @@ -0,0 +1,161 @@ +--- +layout: page +title: Internationalisation (for devs) +--- + +# Internationalisation in the code + +<p class="lead"> + This page describes some technical aspects of internationalising the + Alaveteli code. It's mostly aimed at devs who are working on the + codebase — if you just want to translate Alaveteli into your + own language, see + <a href="{{ site.baseurl }}docs/customising/translation">translating Alaveteli</a> + instead. +</p> + +## Deployment notes + +Deployed translations for the project live in ``locale/``. + +We encourage translations to be done on +[Transifex](https://www.transifex.net/projects/p/alaveteli/) +because translators can work through its web interface rather than needing to edit the +<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` and `.pot` files</a> +directly. Ultimately, Transifex just captures translators' +work and turns it into the files that Alaveteli needs (using gettext). + +### How to get the latest translations onto your site + +For example, to deploy English and Spanish translations at once: + + * Ensure their `.po` files are at ```locale/en/app.po``` and ```locale/es/app.po``` + (for example, by downloading them from Transifex) + * Set <code><a href="{{ site.baseurl }}docs/customising/config/#available_locales">AVAILABLE_LOCALES</a></code> + to <code>en es</code> + +### How to add new strings to the translations + +You need to do this if you've added any new strings to the code that need +translations (or if you change an existing one). + +To update the +<a href="{{ site.baseurl }}docs/glossary/#po" class="glossary__link">`.po` or `.pot` files</a> +for each language, run: + + bundle exec rake gettext:store_model_attributes + +followed by: + + bundle exec rake gettext:find + +If `gettext:find` only creates the file `locale/im-config.pot` then you need to +unset the `TEXTDOMAIN` environment variable and try again. + +For more details about the translations, see the page about +[translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). + + +## Technical implementation details + +### Getting the current locale + +This is complicated by the fact that there are two competing ways to define a +locale+territory combination. The POSIX (and gettext and Transifex) way is +like `en_GB`; the Rails way is like `en-US`. Because we are using gettext and +Transifex for translations, we must deal with both. + + * for the Rails version of the currently selected locale, use `I18n.locale` + * for the POSIX version of the locale, use `FastGettext.locale` + +## I18n in templates + +Before you add i18n strings to the source, you should read +[internationalisation guidelines](http://mysociety.github.io/internationalization.html) +that apply to all our projects. + +Some hints for adding the strings into the Alaveteli code: + +* Simple strings: ```<% = _("String to translate") %>``` +* Strings that include variables: give the translator a hand by inserting + strings that can be interpolated, so the variable has meaning. For example, + ```<%= "Nothing found for '" + h(@query) + "'" %>``` might become ```<%= + _("Nothing found for '{{search_terms}}'", :search_terms => h(@query)) %>``` +* Strings containing numbers: ```<%= n_('%d request', '%d requests', @quantity) % @quantity %>``` +* We allow some inline HTML where it helps with meaningful context, for example: + +``` +_('<a href="{{browse_url}}">Browse all</a> or <a href="{{add_url}}">ask us to add it</a>.', + :browse_url => @browse_url, :add_url => @add_url) +``` + +Similar rules can apply to strings in the Ruby source code. + +## Programmatic access of translated PublicBodies + +Apart from the templates, the only other area of i18n currently implemented is +in the PublicBodies. + +The implementation allows for getting different locales of a PublicBody like so: + +```ruby + PublicBody.with_locale("es") do + puts PublicBody.find(230).name + end +``` + +Usually, that's all the code you need to know about. There's a method +```self.locale_from_params()``` available on all models which returns a locale +specified as ```locale=xx``` in the query string, and which falls back to the +default locale, that you can use in conjunction with the ```with_locale``` +method above. All the joining on internal translation tables should usually be +handled automagically -- but there are some exceptions, that follow below. + +### Overriding model field setters + +Internally, we use the [Globalize plugin](https://github.com/globalize/globalize) +to localize model fields. Where column "foo" has been marked in the model as +```:translates```, globalize overrides ```foo.baz = 12``` to actually set the +value in column ```baz``` of table ```foo_translations```. + +A side effect of the way it does this is that if you wish to override a +specific attribute setter, you will need to explicitly call the Globalize +machinery; something like: + +```ruby + def name=(name) + globalize.write(self.class.locale || I18n.locale, "name", name) + self["name"] = short_name + # your other stuff here + end +``` + +### Searching + +The ```find_first_by_<attr>``` and ```find_all_by_<attr>``` magic methods +should work. If you want to do a more programmatic search, you will need to +join on the translation table. For example: + +```ruby + query = "#{translated_attr_name(someattr) = ? AND #{translated_attr_name('locale')} IN (?)" + locales = Globalize.fallbacks(locale || I18n.locale).map(&:to_s) + find( + :first, + :joins => :translations, + :conditions => [query, value, locales], + :readonly => false + ) +``` + +You may also need to do some lower-level SQL joins or conditions. See +```PublicBodyController.list``` for an example of a query that has a condition +that is explicitly locale-aware (look for the ```locale_condition``` variable) + +## Translation and releases + +The release manager will enforce a translation freeze just before a new release +is cut. During such time, you must not introduce new strings to the code if +your work is due for inclusion in this release. This is necessary to allow +translators time to complete and check their translations against all the known +strings. See more about [translating Alaveteli]({{ site.baseurl }}docs/customising/translation/). + diff --git a/docs/glossary.md b/docs/glossary.md index 64c75c603..d35454cbf 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -27,12 +27,14 @@ Definitions <li><a href="#holding_pen">holding pen</a></li> <li><a href="#newrelic">New Relic</a></li> <li><a href="#mta">MTA</a></li> + <li><a href="#po">.po files</a></li> <li><a href="#production">production site</a></li> <li><a href="#publish">publish</a></li> <li><a href="#recaptcha">recaptcha</a></li> <li><a href="#redact">redacting</a></li> <li><a href="#regexp">regular expression</a></li> <li><a href="#request">request</a></li> + <li><a href="#release">release</a></li> <li><a href="#response">response</a></li> <li><a href="#rails">Ruby on Rails</a></li> <li><a href="#sass">Sass</a></li> @@ -333,6 +335,36 @@ Definitions </dd> <dt> + <a name="po"><code>.po</code> file</a> (and <code>.pot</code> file) + </dt> + <dd> + These are the files needed by the gettext mechanism Alaveteli uses for + localisation. A <code>.pot</code> file is effectively a list of all the + strings in the application that need translating. Each <code>.po</code> + file contains the mapping between those strings, used as keys, and their + translations for one particular language. The key is called the + <em>msgid</em>, and its corresponding translation is the <em>msgstr</em>. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + See <a href="{{ site.baseurl }}docs/customising/translation/">translating + Alaveteli</a> for an overview from a translator's point of view. + </li> + <li> + See <a href="{{ site.baseurl }}docs/developers/i18n/">Internationalising + Alaveteli</a> for more technical details. + </li> + <li> + Alaveteli is on the <a href="https://www.transifex.net/projects/p/alaveteli/">Transifex</a> + website, which lets translators work on Alaveteli in a browser, without needing + to worry about this underlying structure. + </li> + </ul> + </div> + </dd> + + <dt> <a name="production">production site</a> (also: live, production server) </dt> <dd> @@ -378,15 +410,6 @@ Definitions </dd> <dt> - <a name="response">response</a> - </dt> - <dd> - A <strong>response</strong> is the email sent by an - <a href="#authority" class="glossary">authority</a> in reply to - a user's <a href="#request" class="glossary">requests</a>. - </dd> - - <dt> <a name="recaptcha">recaptcha</a> </dt> <dd> @@ -482,6 +505,42 @@ Definitions </dd> <dt> + <a name="release">release</a> (also: release manager) + </dt> + <dd> + We issue new <strong>releases</strong> of the Alaveteli code whenever key + work (new features, improvements, bugfixes, and so on) have been added to + the core code. Releases are identified by their tag, which comprises two or + three numbers: major, minor, and — if necessary — a patch + number. We recommend you always use the latest version. The process is + handled by the Alaveteli <strong>release manager</strong>, who decides what + changes are to be included in the current release, and the cut-off date for + the work. Currently this is Alaveteli's lead developer at mySociety. + <div class="more-info"> + <p>More information:</p> + <ul> + <li> + The latest stable release is on the + <a href="https://github.com/mysociety/alaveteli/tree/master">master branch</a>. + </li> + <li> + See a <a href="https://github.com/mysociety/alaveteli/releases">list of all releases</a> + and their explicit tags. + </li> + <li> + We try to coordinate releases with any active translation work too. + See <a href="http://localhost:4000/docs/customising/translation/">translating + Alaveteli</a> for more information. + </li> + <li> + We encourage you use the <a href="{{site.baseurl}}docs/installing/deploy/">deployment + mechanism</a>, which makes it easier to keep your production server up-to-date. + </li> + </ul> + </div> + </dd> + + <dt> <a name="request">request</a> </dt> <dd> @@ -495,6 +554,15 @@ Definitions </dd> <dt> + <a name="response">response</a> + </dt> + <dd> + A <strong>response</strong> is the email sent by an + <a href="#authority" class="glossary">authority</a> in reply to + a user's <a href="#request" class="glossary">requests</a>. + </dd> + + <dt> <a name="rails">Ruby on Rails</a> (also Rails) </dt> <dd> diff --git a/docs/installing/macos.md b/docs/installing/macos.md index c46bdf4ba..e93ea452f 100644 --- a/docs/installing/macos.md +++ b/docs/installing/macos.md @@ -88,17 +88,27 @@ The following is mostly from [the manual installation process]({{ site.baseurl}} ### Configure database -Creates Alaveteli databases and an `foi` user with password `foi`. - - echo "CREATE DATABASE foi_development encoding = 'UTF8'; - CREATE DATABASE foi_test encoding = 'UTF8'; - CREATE USER foi WITH CREATEUSER; - ALTER USER foi WITH PASSWORD 'foi'; - ALTER USER foi WITH CREATEDB; - GRANT ALL PRIVILEGES ON DATABASE foi_development TO foi; - GRANT ALL PRIVILEGES ON DATABASE foi_test TO foi; - ALTER DATABASE foi_development OWNER TO foi; - ALTER DATABASE foi_test OWNER TO foi;" | psql -h localhost template1 +Create a database for your Mac user as homebrew doesn't create one by default: + + createdb + +Create a `foi` user from the command line, like this: + + createuser -s -P foi + +_Note:_ Leaving the password blank will cause great confusion if you're new to +PostgreSQL. + +We'll create a template for our Alaveteli databases: + + createdb -T template0 -E UTF-8 template_utf8 + echo "update pg_database set datistemplate=true where datname='template_utf8';" | psql + +Then create the databases: + + createdb -T template_utf8 -O foi alaveteli_production + createdb -T template_utf8 -O foi alaveteli_test + createdb -T template_utf8 -O foi alaveteli_development ### Clone Alaveteli diff --git a/docs/installing/manual_install.md b/docs/installing/manual_install.md index fdb836d37..653c6e7f4 100644 --- a/docs/installing/manual_install.md +++ b/docs/installing/manual_install.md @@ -239,20 +239,20 @@ Create a `foi` user from the command line, like this: _Note:_ Leaving the password blank will cause great confusion if you're new to PostgreSQL. -Then create the databases: +We'll create a template for our Alaveteli databases: + + # sudo -u postgres createdb -T template0 -E UTF-8 template_utf8 + # echo "update pg_database set datistemplate=true where datname='template_utf8';" > /tmp/update-template.sql + # sudo -u postgres psql -f /tmp/update-template.sql - # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_production - # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_test - # sudo -u postgres createdb -T template0 -E SQL_ASCII -O foi foi_development +Then create the databases: -We create using the ``SQL_ASCII`` encoding, because in postgres this is means -"no encoding"; and because we handle and store all kinds of data that may not -be valid UTF (for example, data originating from various broken email clients -that's not 8-bit clean), it's safer to be able to store *anything*, than reject -data at runtime. + # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_production + # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_test + # sudo -u postgres createdb -T template_utf8 -O foi alaveteli_development -Now you need to set up the database config file to contain the name, username -and password of your postgres database. +Now you need to set up the database config file so that the application can +connect to the postgres database. * Copy `database.yml-example` to `database.yml` in `alaveteli/config` * Edit it to point to your local postgresql database in the development @@ -262,7 +262,8 @@ Example `development` section of `config/database.yml`: development: adapter: postgresql - database: foi_development + template: template_utf8 + database: alaveteli_development username: foi password: secure-password-here host: localhost @@ -402,28 +403,6 @@ localhost interface by adding `--binding=127.0.0.1` The server should have told you the URL to access in your browser to see the site in action. -## Administrator privileges - -The administrative interface is at the URL `/admin`. - -Only users with the `super` admin level can access the admin interface. Users -create their own accounts in the usual way, and then administrators can give -them `super` privileges. - -There is an emergency user account which can be accessed via -`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and -`ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the -first `super` level accounts, you will need to log in as the emergency -user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. - -Users with the superuser role also have extra privileges in the website -frontend, such as being able to categorise any request, being able to view -items that have been hidden from the search, and being presented with "admin" -links next to individual requests and comments in the front end. - -It is possible completely to override the administrator authentication by -setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`. - ## Cron jobs and init scripts `config/crontab-example` contains the cronjobs run on WhatDoTheyKnow. It's in a diff --git a/docs/running/admin_manual.md b/docs/running/admin_manual.md index 77bacdf1b..cde828c9a 100644 --- a/docs/running/admin_manual.md +++ b/docs/running/admin_manual.md @@ -297,5 +297,24 @@ hanging the application altogether), so please: * Restrict your use of them to cases that can't otherwise be easily covered. * Keep them as simple and specific as possible. +## Administrator privileges +The administrative interface is at the URL `/admin`. +Only users with the `super` admin level can access the admin interface. Users +create their own accounts in the usual way, and then administrators can give +them `super` privileges. + +There is an emergency user account which can be accessed via +`/admin?emergency=1`, using the credentials `ADMIN_USERNAME` and +`ADMIN_PASSWORD`, which are set in `general.yml`. To bootstrap the +first `super` level accounts, you will need to log in as the emergency +user. You can disable the emergency user account by setting `DISABLE_EMERGENCY_USER` to `true` in `general.yml`. + +Users with the superuser role also have extra privileges in the website +front end, such as being able to categorise any request, being able to view +items that have been hidden from the search, and being presented with "admin" +links next to individual requests and comments in the front end. + +It is possible completely to override the administrator authentication by +setting `SKIP_ADMIN_AUTH` to `true` in `general.yml`. diff --git a/docs/running/upgrading.md b/docs/running/upgrading.md index a3b292cf0..2142bfd47 100644 --- a/docs/running/upgrading.md +++ b/docs/running/upgrading.md @@ -5,20 +5,53 @@ title: Upgrading Upgrading Alaveteli ==================== -The developer team policy is that the master branch in git should always -contain the latest stable release. Therefore, in production, you should usually -have your software deployed from the master branch, and an upgrade can be -simply `git pull`. +<p class="lead"> + Alaveteli is under active development — don't let the + version you're running get too far behind our latest + <a href="{{site.baseurl}}docs/glossary/#release" class="glossary__link">release</a>. + This page describes how to keep your site up-to-date +</p> + +## Master branch contains the latest stable release + +The developer team policy is that the `master` branch in git should always +contain the latest stable release -- so you'll be up to date if you pull from +the `master` branch. However, on your +<a href="{{site.baseurl}}docs/glossary/#production" class="glossary">production +site</a>, you should know precisely what version you're running, and deploy +Alaveteli from a [*specific* release +tag](https://github.com/mysociety/alaveteli/releases). + +Upgrading may just require pulling in the latest code -- but it may also require +other changes ("further action"). For this reason, for anything other than a +*patch* (see below), always read the +[`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) +document **before** doing an uprade. This way you'll be able to prepare for any +other changes that might be needed to make the new code work. + +## How to upgrade the code + +* If you're using Capistrano for deployment, + simply [deploy the code]({{site.baseurl}}docs/installing/deploy/#usage): + set the repo and branch in `deploy.yml` to be the version you want. + We recommend you set this to the explicit tag name (for example, + `0.18`, and not `master`) so there's no risk of you accidentally deploying + a new version before you're aware it's been released. +* otherwise, you can simply upgrade by running `git pull` + +## Patches Patch version increases (e.g. 1.2.3 → 1.2.**4**) should not require any further action on your part. +## Minor version increases + Minor version increases (e.g. 1.2.4 → 1.**3**.0) will usually require further -action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) document to see what's changed since -your last deployment, paying special attention to anything in the "Upgrade notes" -sections. +action. You should read the [`CHANGES.md`](https://github.com/mysociety/alaveteli/blob/master/doc/CHANGES.md) +document to see what's changed since your last deployment, paying special attention +to anything in the "Upgrade notes" sections. -Any upgrade may include new translations strings, i.e. new or altered messages +Any upgrade may include new translations strings, that is, new or altered messages to the user that need translating to your locale. You should visit Transifex and try to get your translation up to 100% on each new release. Failure to do so means that any new words added to the Alaveteli source code will appear in @@ -26,7 +59,10 @@ your website in English by default. If your translations didn't make it to the latest release, you will need to download the updated `app.po` for your locale from Transifex and save it in the `locale/` folder. -Unless you're using Capistrano for deployment, you should always run the script `scripts/rails-post-deploy` after each +## Run the post-deploy script + +Unless you're [using Capistrano for deployment]({{site.baseurl}}docs/installing/deploy/), +you should always run the script `scripts/rails-post-deploy` after each deployment. This runs any database migrations for you, plus various other things that can be automated for deployment. |